If you’re starting out with Ruby or Ruby on Rails development, you’ll want to know:
- How to properly install Ruby on Mac.
- How to setup a local development environment that doesn’t conflict with
brewor an existing install of Ruby 2.7 Mac
In this tutorial, you’ll learn how to do both! If you have the new macOS M1 laptops, don’t worry, this tutorial also works for installing Ruby on Mac M1.
Some guides and blog articles will instruct you to install Ruby by running
brew install ruby or updating your existing Ruby versions on a macOS by running the
update ruby mac command. I highly recommend you avoid that completely
If you run commands that change your native Ruby version, such as
brew install ruby or
brew uninstall ruby, then you risk breaking features and capabilities in your macOS (this also applies to Mac M1).
Also, it’s important to point out that the preinstalled version of Ruby on the macOS is outdated, which, on a new 2022 M1 laptop, resolves to
ruby 2.6.8p205. The latest version, Ruby 3.1.2, was released in April 2022, and is a major version upgrade from the one that is preinstalled on the macOS.
You’ll likely want to use Ruby 3 for a local development environment — which is a very good reason to move away from pre-installed Ruby versions. It also gives you the freedom to choose which version you want to work with. To make that magic happen we turn to Ruby virtual environments.
To check which version of the Ruby interpreter you have natively installed, run the command:
If you haven’t upgraded, then the macOS Monterey version ships with Ruby 2.6.8. If you’ve upgraded, or manage Ruby versions using
rvm, or other Ruby version managers, then you might see a different version. Sometimes, you may also find Ruby in the file path
/usr/local/bin/ruby when it is installed with Homebrew package manager for macOS.
The Ruby interpreter is often found natively on the macOS in the file paths
/usr/local/bin/ruby, depending on where it was installed. Ruby gems are installed and managed natively on macOS by the operating system, and using
sudo gem install or making changes in those Ruby gems is discouraged. Instead, consider installing a Ruby virtual environment with a tool like
A great concept that is familiar with other programming languages and their tooling is the Ruby virtual environment. If you’ve used Python’s
virtualenv or Node.js’s
nvm, then Ruby’s
virutalenv should be an easy switch. All you need to get started are a few Ruby ecosystem tools, such as
These tools avoid conflicting with the native Ruby Mac version by fetching the Ruby source code from the internet, compiling it locally, and making it available under a path. They then instruct you to add this new directory path onto your shell of choice, so the new Ruby version is available to use when you open new terminal interfaces.
They are essentially Ruby version manager that allows you to quickly switch between different Ruby runtime versions as needed, depending on the Ruby install directory that was set.
Two popular Ruby virtual environments tools are rbenv and rvm. Since specific environment tools and versions tend to become outdated as the industry progresses, I won’t go into a detailed feature matrix comparison of
rvm1. Instead, I asked some Ruby-savvy developer friends for their opinion, and went with
rbenv since the majority of them recommended it.
Just like many other tools, we turn to the popular Homebrew macOS package manager. Run the following command in your terminal:
brew install rbenv ruby-build
Once everything is installed, we need to instruct rbenv to setup our shell, so we’re using the Ruby runtime version that we’ve customly installed with rbenv whenever we open a new terminal window to type commands in the prompt (as opposed to the preinstalled Ruby 2.6.8 version on the macOS).
To setup rbenv with your shell run the following command:
Follow the on-screen printed instructions if any extra configuration is required on your part. You might be asked to paste a command in your shell’s configuration. If you’re on a macOS and haven’t changed from the default Z Shell (ZSH), then you’ll want to make sure you add the following line of code to the top of your
eval "$(rbenv init - zsh)"
The rbenv install process is now complete. You might want to run some diagnostic checks to ensure that everything is set up correctly. If so, you can run the
rbenv-doctor tool that the rbenv GitHub project provides:
- Open a new terminal window so that you have the new rbenv environment loaded
- Run the command:
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-doctor | zsh
Warning: This command shouldn’t be taken lightly, as you are piping commands into your development environment’s shell that originate from a public and open source GitHub repository. It is possible that a malicious actor had tampered with the source code, so you are highly encouraged to review the code properly before you run this command.
Congrats on building your own Ruby virtual environment! Now that you have a functional rbenv setup we can use it to completely manage your Ruby versions.
To begin, you want to list which Ruby versions are available for installation so you can choose the latest Ruby release, or perhaps a specific version that you’re looking for. To use rbenv to list all Ruby versions, run the following command:
rbenv install -l
The output of which was:
2.6.10 2.7.6 3.0.4 3.1.2 jruby-188.8.131.52 mruby-3.1.0 picoruby-3.0.0 rbx-5.0 truffleruby-22.1.0 truffleruby+graalvm-22.1.0 Only latest stable releases for each Ruby implementation are shown. Use 'rbenv install --list-all / -L' to show all local versions.
You can then proceed to installing one of these Ruby versions. Let’s use rbenv to install a Ruby version of 3.1.2:
rbenv install 3.1.2
The command will then start fetching the relevant source code files to extract, compile, and then install the Ruby 3.1.2 runtime version available to your shell.
When you’ve finished installing it, you should set it to be the chosen version anytime your shell starts. To do that, you need to run:
rbenv global 3.1.2
Finally, you can verify that this is working as expected by running the
ruby --version in your shell, which should output a similar result:
ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [arm64-darwin21]
A note about
rbenv global before we wrap up. Due to the naming of the command (
global), I was concerned that running this command might somehow interfere with the pre-installed macOS Ruby version. This isn’t the case. The command refers to the global user configuration, which is the rbenv configuration file at
~/.rbenv/version, and its meaning is that it isn’t tied to a specific Ruby project / directory.
So, what’s next?
Before you rush off to your Ruby development activities, consider the following resources to make sure your following secure coding conventions and keeping your Ruby gems safe from vulnerabilities. They’re great for Ruby on Rails vulnerabilities that manifest as part of the framework’s Ruby gems, as well as Ruby security vulnerabilities in general.
I highly recommend the following Ruby development and Ruby security related resources:
- If you’re new to Ruby development or don’t fully grasp how open source dependencies in Ruby work, checkout my article for a definitive guide to Ruby gems dependency management.
- If you’re not convinced security vulnerabilities are a thing that impact your projects, I invite you for a quick read from DeveloperSteve’s blog on Better Ruby Gemfile security: A step-by-step guide using Snyk, in which he scans a few projects with Snyk’s security tool for Ruby. Snyk is free to use and makes getting started with Ruby quick and easy.
Lastly, don’t forget to stay alert of malicious remote code execution and other security risks in Ruby gems due to supply chain attacks that we’ve witnessed happening across various ecosystems, Ruby included.
Create a free Snyk account today to keep your ecosystem security on the rails.