| Setup | Using asdf for version management
Using asdf for version management


I recently migrated from rbenv and nvm to asdf and documented the steps I followed. This guide walks through how to install asdf on your Macbook using homebrew.

Reasons to use asdf

Asdf provides you with a single tool for version management. Instead of having separate language specific version managers for ruby, node, go, etc., I can simply use a single tool to manage all of this. In addition to this, asdf defines all dependencies and versions in a single file .tool-versions.

Migrating from an existing version manager (rbenv, nvm)

If you already have a version manager installed, you first need to uninstall your existing version managers to avoid conflicts.

I had both rbenv and nvm installed using homebrew, to uninstall, I simply ran:

brew uninstall rbenv
brew uninstall nvm

Installing asdf

Install asdf using homebrew

 brew install asdf

Add the following to your zsh profile nano ~/.zshrc to always make the asdf command available

echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc

Installing plugins

List all available asdf plugins

asdf plugin list all

If you have a specific plugin you're looking for such as ruby, you can grep for it

asdf plugin list all | grep ruby

Ruby is one of the plugins I'll need to let's go ahead and install the ruby plugin

asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git

See which versions of ruby are available

asdf list all ruby

Install a version of ruby

// Install the latest version
asdf install ruby latest

// install a specific version
asdf install ruby 3.0.3

Setting a global version of a plugin

Set a global ruby version

asdf global ruby 3.0.3

Your global ruby settings are stored here

nano $HOME/.tool-versions

Check that the global version is set properly by navigating to any directory without .tool-versions

ruby -v

Setting a directory-specific version of a plugin

If you have applications that use a different version of ruby than your global version, navigate to the application's root directory and run:

asdf local ruby 3.0.3

The application's root directory will now have a .tool-versions file created which stores your local settings

nano .tool-versions

Check that the global version is set properly by navigating to any directory within your application.

ruby -v