Install Asdf Version Manager
Most developers will need to install newer Ruby versions as they are released. And they will maintain applications that use older Ruby versions. A version manager makes it easy to switch between Ruby versions.
For a version manager, I recommend asdf. Asdf can manage versions of many languages, including Ruby and Node. If you don't need support for multiple languages (you are just using Ruby), see instructions for installing frum or chruby.
Here are instructions for installing asdf. You can also check the asdf installation instructions on the asdf website. Older instructions say you should manually install the coreutils dependencies with Homebrew but I've found that all dependencies are automatically installed by the Homebrew asdf script (the Homebrew "formula").
Is Homebrew installed?
Check if Homebrew is installed:
$ brew doctor
Your system is ready to brew.
If Homebrew is not installed, see the instructions to Install Homebrew.
Install asdf
You can install asdf using Homebrew.
$ brew install asdf
The Homebrew post-installation message for asdf mentions, "zsh completions have been installed to: /opt/homebrew/share/zsh/site-functions" (on Mac M1, M2, M3), meaning that asdf commands are auto-completed by pressing the tab key when you are using the Terminal application.
You can confirm that Homebrew installed asdf with brew list.
$ brew list
==> Formulae
asdf ca-certificates libtool openssl@3
autoconf coreutils libyaml readline
automake gmp m4 unixodbc
After installing asdf with Homebrew, you can view the installed dependencies with brew deps --tree --installed.
Add asdf to the .zshrc file
We must add asdf to the shell environment before we can use it to manage Ruby versions. The Homebrew post-installation message (on Mac M1, M2, M3) for asdf says:
To use asdf, add the following line (or equivalent) to your shell profile
e.g. ~/.profile or ~/.zshrc:
. /opt/homebrew/opt/asdf/libexec/asdf.sh
Use a shortcut to configure your shell to use asdf:
$ echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ~/.zshrc
Check the ~/.zshrc file.
$ cat ~/.zshrc
You should see configuration commands for asdf on the last line.
On Mac M1, M2, M3:
. /opt/homebrew/opt/asdf/libexec/asdf.sh
For Mac Intel:
. /usr/local/opt/asdf/asdf.sh
Configuration for asdf should always be the last line in the ~/.zshrc file, after setting any $PATH configuration.
🚩 Close and reopen the Terminal window for the changes to the ~/.zshrc file to be recognized. Alternatively (this is easier), you can use the source command to reset the shell environment:
$ source ~/.zshrc
After resetting the shell, use asdf --version to check that asdf was installed successfully.
$ asdf --version
v0.13.1
If the asdf command doesn't work, make sure you've added the asdf configuration to your .zshrc file and restarted the Terminal application.
For more about configuring the shell, see Shell Configuration and the Mac Path.
Add the .asdfrc configuration file
If you are working on any older projects that use a .ruby-version file to specify a Ruby version, add a .asdfrc configuration file to your user home directory to enable asdf to read .ruby-version files.
$ echo "legacy_version_file = yes" >> ~/.asdfrc
Confirm the creation of the configuration file.
$ cat ~/.asdfrc
legacy_version_file = yes
Asdf .tool-versions file
When you work on a project, you can tell asdf which language versions you need by adding a .tool-versions file to your project folder. This is a multi-language alternative to configuration with the .ruby-version file.
ruby 3.4.1
nodejs 10.16.0
More
The Uninstall Asdf page explains how to remove asdf, if you decide not to use it.
After installing the Asdf version manager, you can install Ruby.