Published on

Effortless Version Management on Mac: Master asdf-vm Today!

  • avatar
    Ghayoor ul Haq

Managing multiple runtime versions for different projects can be a hassle, especially for developers juggling various languages and frameworks. Enter asdf-vm, a versatile tool that simplifies this process on your macOS. This guide walks you through installing asdf-vm using Homebrew and zsh, and demonstrates its basic usage with Ruby and Node plugins.


There Numerous combinations of shells, operating systems, and installation methods exist that impact the configuration, as noted in the official documentation; however, our approach will employ macOS, Homebrew, and Zsh.


Before diving into the installation process, ensure you have Homebrew installed on your macOS. Homebrew is a package manager that makes it easy to install software and tools. If you haven't installed Homebrew yet, run the following command in your terminal:

/bin/bash -c "$(curl -fsSL"

Installing asdf-vm

With Homebrew ready, you can now install asdf-vm. Open your terminal and execute:

brew install asdf

Now that asdf is installed, add to your ~/.zshrc to ensure it loads correctly in each new shell session.

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


asdf-vm uses plugins to manage different language versions. Lets install plugins for node and ruby and manage their version efficiently.

Adding Plugins

To add plugin, we use command asdf add plugin <plugin>, for node and ruby use command:

asdf plugin add ruby
asdf plugin add nodejs

Installing Language Versions

To install specific versions of Ruby and Node.js, you can use command asdf install <language> <version>, for ruby and node:

asdf install ruby 3.2.2
asdf install nodejs 20.10.0

Remember to replace 3.2.2 and 20.10.0 with the versions you need.

Basic Usage

Setting Global Versions

To set a global version of a language, which will be the default version system-wide, use:

asdf global ruby 3.2.2
asdf global nodejs 20.10.0

Setting Local Versions

For project-specific versions, navigate to your project directory and execute:

asdf local ruby 3.2.2
asdf local nodejs 20.10.0

This creates a .tool-versions file in your project directory, specifying the version for each language.

Tips and Tricks

  • List All Available Versions: To see all available versions for a language, use asdf list-all <language>.
  • Install latest version available: To install latest available versions for a language, use asdf install <language> latest.
  • Updating Plugins: Keep your plugins up-to-date with asdf plugin update --all.
  • Overriding Versions: Temporarily override the set version of a language in your current shell using asdf shell <language> <version>.
  • Complete Guide can be found at official docs


With asdf-vm, managing runtime versions on your Mac becomes a breeze. By following these steps, you can streamline your development process, easily switch between different project environments, and keep your focus on coding.