Asdf Version Manager



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").

Install asdf

You can install asdf using Homebrew.

$ brew install asdf

You can confirm that Homebrew installed asdf with brew list.

$ brew list
==> Formulae
asdf		ca-certificates	libtool		openssl@1.1
autoconf	coreutils	libyaml		readline
automake	gmp		m4		unixodbc

Success. 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 Apple Silicon) for asdf says:

To use asdf, add the following line to your ~/.zshrc:
. /opt/homebrew/opt/asdf/libexec/

The Homebrew post-installation message for asdf also says, "zsh completions have been installed to: /opt/homebrew/share/zsh/site-functions" (on Apple Silicon), meaning that asdf commands are auto-completed by pressing the tab key when you are using the terminal application.

Use a shortcut to configure your shell to use asdf:

$ echo -e "\n. $(brew --prefix asdf)/libexec/" >> ~/.zshrc

Check the ~/.zshrc file.

$ cat ~/.zshrc

You should see configuration commands for asdf on the last line. For Mac Intel:

. /usr/local/opt/asdf/

For me, it is:
. /usr/local/opt/asdf/libexec/

On Apple Silicon:

. /opt/homebrew/opt/asdf/

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.

After closing and reopening the Terminal window, use asdf --version to check that asdf was installed successfully.

$ asdf --version

Mine: 0.11.3 If the asdf command doesn't work, make sure you've added the asdf configuration to your .zshrc file and restarted the terminal application.

You can also check that asdf appears in your $PATH configuration (this is the Apple Silicon version where Homebrew installs packages in /opt/homebrew/):

$ echo $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.1.0
nodejs 10.16.0


The Uninstall Asdf page explains how to remove asdf, if you decide not to use it.

Next you can install Ruby.


Next: Ruby