Getting Started

Hi, we've recently migrated our docs and added some new pages. If you would like to help translate this page, see the "Edit this page" link at the bottom of the page.

asdf installation involves:

  1. Installing dependencies
  2. Installing asdf core
  3. Adding asdf to your shell
  4. install a plugin for each tool/runtime you wish to manage
  5. install a version of the tool/runtime
  6. set 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. Install asdf

We recommend installing via 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. Add to your Shell

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.

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.

Setup Complete!

That completes the initial setup of 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: