asdf/docs/core-manage-asdf-vm.md

Install asdf-vm

** Git **

Clone only the latest branch:

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

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 **

Install using the Homebrew package manager on macOS:

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

** Bash on Linux **

echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.bashrc
echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc

** Bash on macOS **

Installation via Git:

echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.bash_profile
echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bash_profile

Note if you are using Catalina or newer, the default shell has changed to Zsh:

echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.zprofile

Installation via Homebrew:

?> If you have Homebrew's Bash completions configured, the second line below is unnecessary. See Configuring Completions in Bash in the Homebrew docs.

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

** ZSH **

Installation via Git:

Source the asdf.sh script in your shell config:

echo -e "\n. $HOME/.asdf/asdf.sh" >> ~/.zshrc

or use a framework plugin like asdf for oh-my-zsh which will source this init script and setup completions.

ZSH Completions:

asdf ships with ZSH completions which will need to be setup if you're not using a ZSH framework plugin that does this for you. Add the following to your .zshrc:

# append completions to fpath
echo -e "\nfpath=(${ASDF_DIR}/completions $fpath)" >> ~/.zshrc
# initialise completions with ZSH's compinit
echo -e "\nautoload -Uz compinit && compinit" >> ~/.zshrc

• 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 with an asdf plugin, then you shouldn't need to manually add fpath, the plugin may need to be updated to use the new ZSH completions properly

Installation via Homebrew:

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

Shell completions should automatically be installed and available.

** Fish **

Installation via Git:

echo 'source ~/.asdf/asdf.fish' >> ~/.config/fish/config.fish
mkdir -p ~/.config/fish/completions; and cp ~/.asdf/completions/asdf.fish ~/.config/fish/completions

Installation via Homebrew:

?> Homebrew takes care of installing the completions for fish shell. Friendly!

echo "source "(brew --prefix asdf)"/asdf.fish" >> ~/.config/fish/config.fish

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

Having Issues?

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

Plugin Dependencies

?> For most plugins, it is good if you have installed the following packages OR their equivalent on your OS

** macOS **

Installation via Homebrew:

brew install \
  coreutils automake autoconf openssl \
  libyaml readline libxslt libtool unixodbc \
  unzip curl

Installation via Spack:

spack install \
  coreutils automake autoconf openssl \
  libyaml readline libxslt libtool unixodbc \
  unzip curl

** Ubuntu **

sudo apt install \
  automake autoconf libreadline-dev \
  libncurses-dev libssl-dev libyaml-dev \
  libxslt-dev libffi-dev libtool unixodbc-dev \
  unzip curl

Fedora

sudo dnf install \
  automake autoconf readline-devel \
  ncurses-devel openssl-devel libyaml-devel \
  libxslt-devel libffi-devel libtool unixODBC-devel \
  unzip curl

That's all! You are ready to use asdf 🎉

?> If you're migrating from other tools and want to use your existing .node-version or .ruby-version version files, 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 (or .bash_profile if you are on OSX) or .zshrc find the lines that source asdf.sh and the autocompletions. The lines should 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/ ~/.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! 🎉