Getting Started

asdf installation involves:

  1. Installing dependencies
  2. Downloading asdf core
  3. Installing asdf
  4. Installing a plugin for each tool/runtime you wish to manage
  5. Installing a version of the tool/runtime
  6. Setting global and project versions via .tool-versions config files

1. Install Dependencies

Linux:

Package ManagerCommand
Aptitudesudo apt install curl git
DNFsudo dnf install curl git
Pacmansudo pacman -S curl git
Zyppersudo zypper install curl git

macOS:

Package ManagerCommand
HomebrewDependencies will be automatically installed by Homebrew.
Spackspack install coreutils curl git

2. Download asdf

We recommend using Git, though there are other platform specific methods:

MethodCommand
Gitgit clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.8.1
Homebrewbrew install asdf
Pacmangit clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si or use your preferred AUR helperopen in new window

3. Install asdf

There are many different combinations of Shells, OSs & Installation methods all of which affect the configuration here. Expand the selection below that best matches your system:

Bash & Git

Add the following to ~/.bashrc:

. $HOME/.asdf/asdf.sh
1

Completions must be configured by adding the following to your .bashrc:

. $HOME/.asdf/completions/asdf.bash
1
Bash & Git (macOS)

If using macOS Catalina or newer, the default shell has changed to ZSH. Unless changing back to Bash, follow the ZSH instructions.

Add the following to ~/.bash_profile:

. $HOME/.asdf/asdf.sh
1

Completions must be configured manually with the following entry in your .bash_profile:

. $HOME/.asdf/completions/asdf.bash
1
Bash & Homebrew (macOS)

If using macOS Catalina or newer, the default shell has changed to ZSH. Unless changing back to Bash, follow the ZSH instructions.

Add asdf.sh to your ~/.bash_profile with:

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

Completions will need to be configured as per Homebrew's instructionsopen in new window or with the following:

echo -e "\n. $(brew --prefix asdf)/etc/bash_completion.d/asdf.bash" >> ~/.bash_profile
Bash & Pacman

Add the following to ~/.bashrc:

. /opt/asdf-vm/asdf.sh
1

bash-completionopen in new window needs to be installed for the completions to work.

Fish & Git

Add the following to ~/.config/fish/config.fish:

source ~/.asdf/asdf.fish
1

Completions must be configured manually with the following command:

mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions
Fish & Homebrew

Add asdf.fish to your ~/.config/fish/config.fish with:

echo -e "\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fish

Completions are handled by Homebrew for the Fish shellopen in new window. Friendly!

Fish & Pacman

Add the following to ~/.config/fish/config.fish:

source /opt/asdf-vm/asdf.fish
1

Completions are automatically configured on installation by the AUR package.

ZSH & Git

Add the following to ~/.zshrc:

. $HOME/.asdf/asdf.sh
1

OR use a ZSH Framework plugin like asdf for oh-my-zshopen in new window which will source this script and setup completions.

Completions are configured by either a ZSH Framework asdf plugin or by adding the following to your .zshrc:

# append completions to fpath
fpath=(${ASDF_DIR}/completions $fpath)
# initialise completions with ZSH's compinit
autoload -Uz compinit && compinit
1
2
3
4
  • if you are using a custom compinit setup, ensure compinit is below your sourcing of asdf.sh
  • if you are using a custom compinit setup with a ZSH Framework, ensure compinit is below your sourcing of the framework

Warning

If you are using a ZSH Framework the associated asdf plugin may need to be updated to use the new ZSH completions properly via fpath. The Oh-My-ZSH asdf plugin is yet to be updated, see ohmyzsh/ohmyzsh#8837open in new window.

ZSH & Homebrew

Add asdf.sh to your ~/.zshrc with:

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

OR use a ZSH Framework plugin like asdf for oh-my-zshopen in new window which will source this script and setup completions.

Completions are configured by either a ZSH Framework asdf or will need to be configured as per Homebrew's instructionsopen in new window. If you are using a ZSH Framework the associated plugin for asdf may need to be updated to use the new ZSH completions properly via fpath. The Oh-My-ZSH asdf plugin is yet to be updated, see ohmyzsh/ohmyzsh#8837open in new window.

ZSH & Pacman

Add the following to ~/.zshrc:

. /opt/asdf-vm/asdf.sh
1

Completions are placed in a ZSH friendly location, but ZSH must be configured to use the autocompletionsopen in new window.

asdf scripts need to be sourced after you have set your $PATH and after you have sourced your framework (oh-my-zsh etc).

Restart your shell so that PATH changes take effect. Opening a new terminal tab will usually do it.

Core Installation Complete!

This completes the installation of the asdf core 🎉

asdf is only useful once you install a plugin, install a tool and manage its versions. Continue the guide below to learn how to do this.

4. Install a Plugin

For demonstration purposes we will install & set Node.jsopen in new window via the asdf-nodejsopen in new window plugin.

Plugin Dependencies

Each plugin has dependencies so we need to check the plugin repo where they should be listed. For asdf-nodejs they are:

OSDependency Installation
Linux (Debian)apt-get install dirmngr gpg curl gawk
macOSbrew install gpg gawk

We should install dependencies first as some Plugins have post-install hooks.

Install the Plugin

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

5. Install a Version

Now we have a plugin for Node.js we can install a version of the tool.

We can observer which versions are available with asdf list all nodejs or a subset of versions with asdf list all nodejs 14.

We will just install the latest available version:

asdf install nodejs latest

Note

asdf enforces exact versions. latest is a helper throughout asdf that will resolve to the actual version number at the time of execution.

6. Set a Version

asdf performs a version lookup of a tool in all .tool-versions files from the current working directory up to the $HOME directory. The lookup occurs just-in-time when you execute a tool that asdf manages.

WARNING

Without a version listed for a tool execution of the tool will error. asdf current will show you the tool & version resolution, or absence of, from your current directory so you can observe which tools will fail to execute.

Global

Global defaults are managed in $HOME/.tool-versions. Set a global version with:

asdf global nodejs latest

$HOME/.tool-versions will then look like:

nodejs 16.5.0
1

Some OSs already have tools installed that are managed by the system and not asdf, python is a common example. You need to tell asdf to pass the management back to the system. The Versions reference section will guide you.

Local

Local versions are defined in the $PWD/.tool-versions file (your current working directory). Usually, this will be the Git respository for a project. When in your desired directory execute:

asdf local nodejs latest

$PWD/.tool-versions will then look like:

nodejs 16.5.0
1

Using Existing Tool Version Files

asdf supports the migration from existing version files from other version managers. Eg: .ruby-version for the case of rbenv. This is supported on a per-plugin basis.

asdf-nodejsopen in new window supports this via both .nvmrc and .node-version files. To enable this, add the following to your asdf configuration file $HOME/.asdfrc:

legacy_version_file = yes
1

See the configuration reference page for more config options.

Guide Complete!

That completes the Getting Started guide for asdf 🎉 You can now manage nodejs versions for your project. Follow similar steps for each type of tool in your project!

asdf has a many more commands to become familiar with, you can see them all by running asdf --help or asdf. The core of the commands are broken into three categories: