Search code examples
rubyhomebrew

How to change which version of Ruby I am using

I need to run 2.5.3. I use brew to manage my ruby installation (as I couldn't get rvm to work on my machine). When I run

$ruby -v

I get

ruby 2.3.7p456 (2018-03-28 revision 63024) [universal.x86_64-darwin18]

However when I attempt to update it using 

brew upgrade ruby

I get 

Error: ruby 2.6.1 already installed

Why is it so inconsistent on what ruby version I really have installed?

Solution

  • You should be using a Ruby version manager to manage multiple versions of Ruby. I prefer using rbenv. Following are the steps to install it on a mac (they are explained in detail about what is being done and why; if you want a shortcut, try running all the commands in sequence but I'd still insist you read through the steps).

    rbenv

    Before proceeding with the actual installation, remember these points:

    1. rbenv in itself does not include the ability to install ruby versions. It only changes ruby version per directory. For installing rubies, you need to install the ruby-build tool (which is part of the rbenv project). It is the same for chruby as well which uses another tool to build ruby. EDIT (June 2021): It looks like rbenv installations now come with ruby-build and are capable of compiling ruby right on your machine. I will leave the answer as it is for so that it makes sense for someone on an older setup (or in case they revert that decision later).
    2. ruby-build has to be installed as a plugin to rbenv.
    3. In case you need to learn about the tools in detail, here are the links for rbenv and ruby-build.
    4. The installation procedure for both tools (and a lot of other help) is available in the README files for the projects. Refer to those if things don't work for you.

    Installing rbenv

    Run the following command to clone rbenv repo into .rbenv directory in your home directory.

    $ git clone https://github.com/rbenv/rbenv.git ~/.rbenv

    Your system still does not know where rbenv is. Add it to your path by running:

    $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile

    To initialize rbenv so that it can help you with changing rubies when you change directories, run this:

    ~/.rbenv/bin/rbenv init

    This should tell you something like this:

    # Load rbenv automatically by appending
# the following to ~/.bash_profile:

eval "$(rbenv init -)"

    So run this:

    echo 'eval "$(rbenv init -)"' >> ~/.bash_profile

    By this point rbenv should be installed. When you run rbenv on the command line, you should get something like this:

    $ rbenv
rbenv 1.1.1-39-g59785f6
Usage: rbenv <command> [<args>]

Some useful rbenv commands are:
   commands    List all available rbenv commands
   local       Set or show the local application-specific Ruby version
   global      Set or show the global Ruby version
   shell       Set or show the shell-specific Ruby version
   rehash      Rehash rbenv shims (run this after installing executables)
   version     Show the current Ruby version and its origin
   versions    List all Ruby versions available to rbenv
   which       Display the full path to an executable
   whence      List all Ruby versions that contain the given executable

See `rbenv help <command>' for information on a specific command.
For full documentation, see: https://github.com/rbenv/rbenv#readme

    NOTE: If you get a warning saying that rbenv is not installed, just run source ~/.bash_profile. That will rerun the ~/.bash_profile script and get rbenv in your path. You should be able to run rbenv after that without trouble.

    Do notice that rbenv does not give an option to install or uninstall rubies yet. For this we need to install ruby-build.

    Installing ruby-build

    We need to add the ruby-build package as a rbenv plugin so that we can type rbenv install <ruby version> to install rubies. All you need to do is to create the plugins directory and checkout the git repo for ruby-build in the plugins directory. Run the following:

    $ mkdir -p "$(rbenv root)"/plugins
$ git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

    Testing if rbenv and ruby-build have been installed

    Run rbenv without any arguments on the terminal should now show the install and uninstall commands being available. Something like this:

    $ rbenv
rbenv 1.1.1-39-g59785f6
Usage: rbenv <command> [<args>]

Some useful rbenv commands are:
   commands    List all available rbenv commands
   local       Set or show the local application-specific Ruby version
   global      Set or show the global Ruby version
   shell       Set or show the shell-specific Ruby version
   install     Install a Ruby version using ruby-build
   uninstall   Uninstall a specific Ruby version
   rehash      Rehash rbenv shims (run this after installing executables)
   version     Show the current Ruby version and its origin
   versions    List all Ruby versions available to rbenv
   which       Display the full path to an executable
   whence      List all Ruby versions that contain the given executable

See `rbenv help <command>' for information on a specific command.
For full documentation, see: https://github.com/rbenv/rbenv#readme

    If you see that output, your rbenv is installed properly.

    Installing ruby

    To install ruby 2.5.3, you could run (wait, don't run it yet):

    rbenv install 2.5.3

    It should output a few lines, take some time and then tell you that version 2.5.3 was installed. However, there is a problem - if the installation fails, especially during compilation, sometimes, the terminal gets stuck and there is no output on the terminal. It just appears to be installing for a long time (forever). To get more info about what is happening, run the following:

    rbenv install -f -v 2.5.3

    The -f argument tells rbenv to force-install the given version. So if it is already installed, rbenv will re-install (basically overwrite) the given version. So if an installation failed, -f will make sure of the installation.

    The -v argument tells rbenv to output verbose messages. So everything that ruby-build does (including the compilation process) will be shown to you. Don't be afraid by the word compilation here. It normally compiles fine without troubles and does not alter your system ruby (the one installed with sudo apt install ruby on Linux or the one you get by default on macOS) whether it succeeds or fails.

    Test installation

    Once the installation succeeds, you can run the command below to check which versions are installed (output included in the snippet below):

    $ rbenv versions
  system
* 2.5.3 (set by /home/ubuntu/.rbenv/version)

    Note: On mac, the newly installed ruby will have a different path.

    The one with the * in front of it is the one which is active right now. If you run which ruby, you should get a path with a ruby shim. If you are curious, read the rbenv documentation to know what shims are, though you wouldn't have to worry about them.

    $ which ruby 
/home/ubuntu/.rbenv/shims/ruby

    Configure & Forget

    rbenv is a cool thing to have but to keep writing rbenv shell 2.5.3 and rbenv shell 2.4.5 every single time is a problem. What you should instead do is set a version of ruby for the directory and forget about rbenv.

    You can just create a file named .ruby-version containing one line - the version number of ruby you want to use for all ruby scripts within this directory (and subdirectories). Just cd to the required directory and run:

    echo "2.5.3" > .ruby-version

    All ruby scripts within that directory and subdirectories will then use version 2.5.3.