Manage runtime versions with asdf

Install asdf, add language plugins, and use .tool-versions with explicit installation and legacy-file requirements.

Guance Editorial Team 3 min read Updated 2026-10-20

Illustration of software development and testing

asdf provides one interface for installing and selecting versions of tools such as Ruby, Node.js, Python, Go, and Terraform. Plugins supply tool-specific installation logic, while .tool-versions records the versions a project expects.

Why use one version manager?

A Rails application, a frontend service, and a data pipeline can need different runtimes. Separate managers such as rbenv, nvm, and pyenv each bring their own setup and commands. asdf offers a common workflow across those tools.

Once asdf, the required plugins, and build dependencies are installed, asdf install in a project directory installs the versions declared in .tool-versions. Installing asdf alone does not automatically install every plugin or system dependency.

Install asdf

On a supported macOS or Linux system with Homebrew:

brew install asdf

Place the shim directory early in PATH in the relevant shell startup file:

export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

Open a new terminal and check asdf --version. asdf 0.16 and later use the Go implementation; do not reuse old instructions that source asdf.sh. For other installation methods and supported platforms, follow the current official guide.

Add language plugins

asdf plugin add ruby
asdf plugin add nodejs
asdf plugin add python

asdf plugin list all lists the plugin index, including tools such as Erlang, Elixir, Java, kubectl, and Terraform. Plugins implement the download, build, and installation steps for their tools. Check a plugin's requirements before installing it; support and dependencies vary.

Install and select versions

The following version numbers illustrate the commands, not a recommendation to deploy these historical releases:

asdf install ruby 3.3.0
asdf install nodejs 20.11.0
asdf install ruby latest

Install every version you plan to select. Then choose the scope:

asdf set -u ruby 3.3.0        # Write the user-level .tool-versions file.
asdf set ruby 3.2.2          # Write .tool-versions in the current directory.
export ASDF_RUBY_VERSION=3.1.4 # Override selection in this shell.

asdf set selects a version; it does not install it. In this example, install Ruby 3.2.2 and 3.1.4 before using those selections. Directory-based selection works through the shims and applicable .tool-versions file. Commit the project file to Git so teammates can reproduce the intended versions.

Read legacy version files

To enable a plugin's legacy-file support, add this to ~/.asdfrc:

legacy_version_file = yes

The setting only enables behavior implemented by a plugin. Ruby and Node plugins can support files such as .ruby-version and .nvmrc; check the particular plugin and supported value formats rather than assuming every legacy file works automatically.

Frequently asked questions

Does asdf conflict with Docker?

They address different layers. asdf selects tools on the development machine; a container image packages a runtime environment. Local asdf use and container-based deployment can coexist.

Why does Ruby fail to compile?

Missing build dependencies are a common cause. Depending on the Ruby and operating-system versions, macOS may need packages such as openssl@3, readline, libyaml, and gmp; Ubuntu may need build-essential, libssl-dev, libreadline-dev, and libyaml-dev. Use the plugin's Ruby-build guidance to check the exact requirements and inspect the actual compiler error before retrying.

How do I update asdf and its plugins?

For a Homebrew installation, run brew upgrade asdf. Update plugins with asdf plugin update --all. New language releases often require updated plugin or build definitions rather than a new asdf core release, but plugin compatibility requirements still apply.