Rails is not currently installed on this system: how to fix this error

Updated

Did you just install Rails on your Mac, but got “Rails is not currently installed on this system” when you tried to use it?

Depending on how you installed Rails, the fix could be easy or complicated. Whatever you do, please don’t follow the instructions to simply type sudo gem install rails. Learn why you should never use sudo to install gems.

This error could also be due to how you installed Ruby. If you used rbenv, your system might not immediately recognize gems after installing them. This isn’t an issue with chruby, which is why it’s the Ruby version manager I recommend.

If you installed Ruby with Homebrew instead of a version manager, the first 3 solutions below are not going to help. I recommend going directly to Install Rails with chruby and ruby-install.

Here are five ways to fix the error “Rails is not currently installed on this system”:

Quit and restart Terminal

When you make changes to your development environment, they might not take effect right away. This is one of the most common sources of confusion, and quitting and restarting Terminal will solve many problems. Just like turning it off and on again.

If that doesn’t work, try the next solution in this guide.

Install Rails again

Another common scenario where a gem might not be found is when switching between Ruby versions. If you installed Ruby with a version manager (such as chruby, rbenv, asdf, or rvm), you’ll need to install gems separately in each version of Ruby.

For example, if you first installed Rails while using Ruby 3.1.2, and then you installed and switched to Ruby 2.7.6, Rails won’t be there automatically. You’ll need to run gem install rails again in each version of Ruby that you install.

If that doesn’t work either, try the next solution in this guide.

Switch to the correct Ruby version

Depending on how you installed Ruby, and whether or not you configured it properly, you might not be using your desired Ruby version. Anytime you cd into a new directory, you should check that you’re using the intended Ruby version:

ruby -v

If you were expecting 3.1.2 but you got 2.6.8, for example, then try switching manually to the desired version. The command for doing that will depend on which version manager you’re using. With chruby, the version manager I recommend, it would be like this:

chruby 3.1.2

Then check the version again:

ruby -v

If it still doesn’t show your desired version, then try the next solution.

Install Rails with chruby and ruby-install (most reliable)

Of all the possible ways to install Rails on a Mac, I recommend using a Ruby manager. This allows you to have multiple versions of Ruby installed at the same time, and makes it easy to switch between them. And of all the Ruby managers, I recommed chruby and ruby-install because they’re the most reliable and easiest to use.

Even if you don’t think you’ll need more than one Ruby version now, it’s worth your time to learn how to use a Ruby version manager because you’ll inevitably need one.

Over the past ten years, I’ve helped thousands of people set up Ruby on their Mac. From clean Macs to the most obscure issues, I’ve seen and fixed it all. And the most reliable solution is to use a version manager, specifically chruby.

You have two options for setting up a proper Ruby environment with chruby:

Have everything set up for you in 15 minutes or less with a single command

My paid script Ruby on Mac (released in February 2022) will automatically install Ruby with chruby, ruby-install, and all the other development tools you’ll need for Rails. Over 700 happy customers have saved so much time and frustration.

When you buy Ruby on Mac today, you’ll be supporting an independent developer, and if you need it for your job or business, you should be able to expense it.

Read what people say about Ruby on Mac, and here are more Twitter testimonials.

Spend an hour or more setting everything up manually

Follow my free step-by-step guide for installing Ruby on Mac with chruby and ruby-install. This will only give you the bare minimum setup, which is the manual equivalent of the “Basic” version of Ruby on Mac, minus the comprehensive troubleshooting guide. The guide also works best when you’re starting with a clean Mac.

Update your PATH (time-consuming and complicated)

For your computer to know about a command, gem, or other executable program, it has to be told where to look for it. It wouldn’t be efficient for the computer to search the entire hard drive for the program. Instead, it looks in a specific list of locations, which are stored in an environment variable called PATH. You can view this list by running this command in your terminal:

echo $PATH

When you install new programs, such as Rails, they might get installed in a location that is not already included in the PATH. If you don’t add this new location to the PATH, the computer won’t know to look for it there, and so it thinks it doesn’t exist.

With my Ruby on Mac script, you don’t have to worry about any of this. It detects and configures everything automatically.

For a more in-depth guide on PATH and how to add locations to it, read my guide about troubleshooting command not found.

The location where Rails was installed depends on how you installed Ruby. If you installed Ruby with Homebrew (which I don’t recommend), you probably missed this instruction to add the Homebrew gems location to your PATH:

By default, binaries installed by gem will be placed into:
  /usr/local/lib/ruby/gems/3.1.0/bin

You may want to add this to your PATH.

On an Apple Silicon (M1/M2) Mac, depending on whether or not you ran Terminal in Rosetta mode, it might refer to /opt/homebrew instead of /usr/local.

But if you don’t know how to add things to your PATH, that message is not very helpful. Here’s one way to add it to your PATH:

echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.1.0/bin:$PATH"' >> ~/.zshrc

Replace .zshrc with .bash_profile if you’re using bash. If you’re not sure, read my guide to find out which shell you’re using.

And if you’re on an M1 Mac and you didn’t use Rosetta when you installed Homebrew, then replace all instances of /usr/local in the command above with /opt/homebrew.

The 3.1.0 in the command above assumes Homebrew installed a Ruby version that starts with 3.1. If you’re using a different version (which you can check with ruby -v), replace 3.1 with the first two digits of your Ruby version.

Once you’ve updated your PATH, quit and restart your terminal, then verify that the Homebrew gems directory is included in the GEM PATHS section when running this command:

gem env

Then install Rails again to be sure it’s installed:

gem install rails

Then quit and restart your Terminal, and now you should be able to use the rails command:

rails -v

While this solution works, I don’t recommend continuing to use Ruby as managed by Homebrew because you won’t be able to easily switch between different Ruby versions. This will cause you confusion and headaches sooner or later.

Instead, I recommend using a version manager like chruby, which is what my Ruby on Mac script uses to set up a proper Ruby environment so you can be up and running with Rails in minutes.