Racing Turtles

asdf - Manage Your Version Managers

Install and use the asdf version manager.



Version managers let you install and switch between multiple versions of a technology. Little software exists to manage your version managers. Node needs nvm. Python needs pyenv. Ruby needs rbenv. Different version managers need to be handled separately.

You might struggle remembering which command to use for which technology. Each version manager uses a different command scheme to set, install, and remove versions of the technology they manage. You need to maintain a long PATH to manage each technology yourself.

The asdf version manager lets you manage your version managers. You only need to install one version manager and add a few lines to your shell configuration file once. This tutorial will help you install the asdf version manager and install the latest version of Node.js without root privileges.

Requirements #

Author Recommends

This tutorial details installing asdf on a Linux distribution. If you run Windows or OS X, refer to the official documentation here.

The official asdf documentation details other installation methods, but I recommend using git and a POSIX-compliant shell because they don't require many dependencies on most Linux distributions.

Getting Started #

You can view the asdf version manager's official git repository here.

To install asdf with git and a POSIX-compliant shell:

  1. Clone the git repository into your home directory.
  2. Add lines to your shell configuration file to:
    • Set $ASDF_DIR environment variable to location of installation directory.
    • Source asdf environment variables.

1. Clone Repository #

To clone the git repository, enter the git clone command shown below:

$ git clone https://github.com/asdf-vm/asdf.git ~/.asdf

This will create a hidden directory named .asdf/ in your home directory, which will contain the installations and binaries for each version of every technology installed.

2. Edit Configuration File #

To use asdf in the shell, add lines to the file ~/.profile. Open the file in a text editor.

Author Recommends

I recommend nano if you're unsure of which text editor to use.

To save a file and exit in nano, type <C-x>y<CR>.

To set the ASDF_DIR environment variable in the shell, add the following line to the end of the ~/.profile file:

export ASDF_DIR="$HOME/.asdf"

This will help asdf find the location of your installs and binaries.

To source the environment variables, add the following line to the end of the ~/.profile file:

. "$HOME/.asdf/asdf.sh"

This will help asdf update the PATH variables for each version of every technology installed.

Save and close the file from your text editor.

Update the environment variables in the shell by running the following command in the shell:

$ . ~/.profile

Install Technology #

With asdf installed, you can begin adding technologies. The asdf version manager has first party (built by the developer of asdf) and community plugins to install various technologies, for example Node.js, Ruby, and Java. This tutorial details starting with the nodejs plugin because it is a first party plugin, and it installs node and npm, which allows any npm package to be installed.

To install the latest version of Node.js and use it in the shell:

  1. Add Node.js plugin to asdf
  2. Install latest version of Node.js
  3. Set latest version of Node.js as default globally

1. Add Plugin #

To add the Node.js plugin, enter the asdf plugin add command into a shell:

$ asdf plugin add nodejs

2. Install Latest Version #

To install the latest version of Node.js, enter the asdf install command, followed by the plugin and the version. The asdf version manager's Node.js plugin provides the term latest to indicate the latest stable version of Node.js currently released.

$ asdf install nodejs latest

This command will pull the latest stable version of Node.js currently released into the installs/ folder under the ~/.asdf/ directory where asdf was installed.

Double-check that the latest version of Node.js was installed with the asdf list command followed by the plugin name. At the time of writing this tutorial, v22.3.0 was the latest version of Node.js released.

$ asdf list nodejs
 *22.3.0

3. Set Node.js Version #

Set Global Version #

To set a Node.js version globally, use the asdf global command followed by the name of the plugin and the version to set. If you installed the latest version of Node.js with the term latest to denote the version, you can use latest to set the latest stable version of Node.js released globally.

$ asdf global nodejs latest

Set Local Version #

To set a Node.js version locally, use the asdf local command followed by the name of the plugin and the version to set. You can use latest to denote the latest Node.js version released.

$ asdf local nodejs latest

Verify Version #

To check whether Node.js is installed, run node -v in a shell. At the time of writing this tutorial, v22.3.0 was the latest version of Node.js released.

$ node -v
v22.3.0

Another way to check the currently set version of a plugin is to use the asdf current command followed by the plugin name. At the time of writing this tutorial, v22.3.0 was the latest version of Node.js released.

$ asdf current nodejs
nodejs          22.3.0          /home/user/.tool-versions

Troubleshooting #

If you receive a command not found error after running , you might need to run the asdf reshim command in a shell to move the correct binary from the installs/ directory into the shims/ directory so you can access the binary in the shell.

$ asdf reshim

Try node -v again to see if the correct version of Node.js is installed. Double-check that the node binary is taken from the asdf install by running the which node command in a shell.

$ which node
/home/user/.asdf/shims/node

If your Node.js binary isn't installed in the ~/.asdf/ directory, check your PATH with the echo $PATH command. Make sure you receive the following output:

$ echo $PATH
/home/user/.asdf/shims:/home/user/.asdf/bin:...

Conclusion #

The asdf version manager simplifies the commands needed to install and set versions of your technologies. With the method described in this tutorial, you don't need root privileges to install asdf, and you will never need root privileges to install plugins. You installed Node.js as an example, and you can find plugins to install other technologies in this Git repository.

References #

The official documentation for asdf can be accessed here.

License #

This work is licensed under CC BY 4.0.