asdf for Managing Multiple Tool Runtime Versions

If you read my prior blog posts, Managing Multiple Python Versions and Packages and Managing Multiple Python Installs and Packages with Pyenv and Pipenv, you’re aware of how I prior used Pyenv and Pipenv to install, manage, and use multiple python runtimes and associated python packages. More recently I tried asdf and was blown away by the simplicity and ability to use it for managing multiple runtimes for different languages (not just Python) with one CLI tool. asdf is a tool version manager and employs a plugin architecture, so, for instance, you can install Python plugin and the Node.js plugin if you require multiple runtimes for both. You can read more on the asdf site here. In this post, I show you how you can quickly get going using asdf; my instructions below are specific to MacOS.

Below are the six steps to get going with asdf:

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

First step is to install dependencies for asdf.
brew install coreutils curl git

Next, download asdf.
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.11.1

Thrid, install asdf. My install is specific to using ZSH and Git.

Add the below to ~/.zshrc.

#initialise completions with ZSH's compinit
autoload -Uz compinit && compinit


Restart your shell so that PATH changes take effect; you can accomplish this by opening a new terminal tab.

In the future you can easily update asdf with the below command.
asdf update

Now core asdf has been installed, but to be able to actually do something useful, you have to install a plugin for the tool you want to use, install the tool itself, and then manage its versions. I demonstrate below using python as the tool I want to support.

Install python plugin.
asdf plugin-add python

If you desire to use another tool like node.js, you would simply install the node.js plugin; you can install as many plugins as you like.
asdf plugin-add nodejs

To see a list of all tool plugins available, you can use the below command.
asdf plugin list all

Next, install the runtime of for the tool that you would like to use.
asdf install python 3.11.1

You can set the package global version with the below command.
asdf global python 3.11.1

You can now check which python version would be used via the below command.
python --version

You can look at all the python runtimes available to install via below command.
asdf list all python

You can see all the python runtimes installed via below command.
asdf list python

To install and use a different python runtime local to a specific directory, first install the runtime and then simply navigate to the respective directory (ex: MyTestProject), and use asdf to configur the python runtime to use locally.

asdf install python 3.9.10
cd MyTestProject
asdf local python 3.9.10


You can test again under the respective directory via “python –version” command to ensure the correct python version is being utilized.

Check the asdf site for a list of all commands available.

You can see asdf is very powerful tool for managing tool runtimes, yet very operationally simple.

Follow me on Twitter: @Humair_Ahmed