asdf/docs/core-manage-asdf.md

1. Manage asdf: install asdf and add asdf to your shell
2. Manage Plugins: add a plugin for your tool asdf plugin add nodejs
3. Manage Versions: install a version of that tool asdf install nodejs 13.14.0
4. Configuration: set global and project tool versions via .tool-versions config

Install

Dependencies

-- Linux,Aptitude --

sudo apt install curl git

-- Linux,DNF --

sudo dnf install curl git

-- Linux,Pacman --

sudo pacman -S curl git

-- Linux,Zypper --

sudo zypper install curl git

-- macOS,Homebrew --

brew install coreutils curl git

-- macOS,Spack --

spack install coreutils curl git

-- Docsify Select Default --

No match for Operating System and Installation Method selections. Please try another combination.

asdf

--Git--

Clone only the latest branch:

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.8.0

Alternately, you can clone the whole repo and checkout the latest branch:

git clone https://github.com/asdf-vm/asdf.git ~/.asdf
cd ~/.asdf
git checkout "$(git describe --abbrev=0 --tags)"

--Homebrew--

!> See asdf and Homebrew compatibility issues in #785 before continuing.

Install using the Homebrew package manager:

brew install asdf

To use the latest changes, you can point Homebrew to the master branch of the repo:

brew install asdf --HEAD

Add to your Shell

--Linux,Bash,Git--

Add the following to ~/.bashrc:

. $HOME/.asdf/asdf.sh

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

. $HOME/.asdf/completions/asdf.bash

--Linux,Fish,Git--

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

source ~/.asdf/asdf.fish

?> Completions must be configured manually with the following command:

mkdir -p ~/.config/fish/completions; and cp ~/.asdf/completions/asdf.fish ~/.config/fish/completions

--Linux,ZSH,Git--

Add the following to ~/.zshrc:

. $HOME/.asdf/asdf.sh

OR use a ZSH Framework plugin like asdf for oh-my-zsh 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

• 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

!> 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 https://github.com/ohmyzsh/ohmyzsh/pull/8837.

--macOS,Bash,Git--

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

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

. $HOME/.asdf/completions/asdf.bash

--macOS,Fish,Git--

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

source ~/.asdf/asdf.fish

?> Completions must be configured manually with the following command:

mkdir -p ~/.config/fish/completions; and cp ~/.asdf/completions/asdf.fish ~/.config/fish/completions

--macOS,ZSH,Git--

Add the following to ~/.zshrc:

. $HOME/.asdf/asdf.sh

OR use a ZSH Framework plugin like asdf for oh-my-zsh 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

• 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

!> 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 https://github.com/ohmyzsh/ohmyzsh/pull/8837.

--macOS,Bash,Homebrew--

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)/asdf.sh" >> ~/.bash_profile

?> Completions will need to be configured as per Homebrew's instructions or with the following:

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

--macOS,Fish,Homebrew--

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

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

?> Completions are handled by Homebrew for the Fish shell. Friendly!

--macOS,ZSH,Homebrew--

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

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

OR use a ZSH Framework plugin like asdf for oh-my-zsh 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 instructions. 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#8837.

--Docsify Select Default--

!> The Homebrew asdf Formulae has not been tested on Linux by the core asdf team. Please raise an issue if this has changed and we will update the docs.

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

You are ready to use asdf 🎉

Having Issues?

If you're having issues with your shell not detecting newly installed shims, it's most-likely due to the sourcing of asdf.sh or asdf.fish not being at the BOTTOM of your .bash_profile, .zshrc, config.fish config file. It needs to be sourced AFTER you have set your $PATH and AFTER you have sourced your framework (oh-my-zsh etc).

Migrating Tools

If you're migrating from other tools and want to use your existing version files (eg: .node-version or .ruby-version), look at the legacy_version_file flag in the configuration section.

Update

-- Git --

asdf update

If you want the latest changes that aren't yet included in a stable release:

asdf update --head

-- Homebrew --

brew upgrade asdf

Remove

Uninstalling asdf is as simple as:

1. In your .bashrc/.bash_profile/.zshrc/config.fish find the lines that source asdf.sh and the completions (this may be a ZSH Framework plugin). In Bash, the lines look something like this:

   . $HOME/.asdf/asdf.sh
   . $HOME/.asdf/completions/asdf.bash
   

   Remove these lines and save the file.

2. Run

   rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} ~/.tool-versions
   

   to completely remove all the asdf files from your system.

3. (Optional) If you installed asdf using a package manager, you may want to use that package manager to uninstall the core asdf files.

That's it! 🎉