• Matheus Lozano

An easy way to switch between runtime versions  -  NodeJS, Terraform, and +279

A CLI tool that can easily manage more than 281 runtimes, and it’s easy to add custom runtimes/plugins. It’s open-source!

How to keep tools updated. How to switch between versions on Linux
Screenshot from asdf website

Replica: https://lozanomatheus.medium.com/53fdfbcb4049?source=friends_link&sk=43548418bf394d80e277a39a76070843


There are many tools out there that promise to manage multiple runtimes and/or runtime versions, some are exclusive to a specific language, like the pyenv and others can manage multiple runtimes, but it’s not easy to switch between the versions of the same runtime, like the Homebrew (You can unlink/link, but in my opinion, it’s too unstable).

Here comes the asdf, yes, this is the name. Simple name, simple to use! asdf is an open-source tool under the MIT License. Currently, it supports 281 runtimes, also known as plugins. You can use it to switch between runtimes versions or just to keep things updated.

asdf is very easy to use, it's very intuitive, and it’s easy to customize in case you want to add/change plugins.


Thanks to most of the shell builtin, asdf don't have a long list of requirements.

These are the basic requirement to use asdf. Other requirements may be included. Some plugins need to be compiled (e.g.: via Makefile), others use wget or curl to download the binary.

  • Bash / Zsh / Fish

  • Git

How it works

asdf is a, let's say, Bash toolbox. Most of the commands used are shell builtin and this is one of the greatest things about this tool, and it's why is portable to other Operational Systems, you can even run on Windows (it needs a bit of customization, but it’s possible).


Each plugin is a runtime that points to a git repository and contains all the basic functions, like list the versions available and what needs to be done to install the plugin. The plugin's git repository is also a collection of Bash scripts.


There are three scopes that you can install a plugin version.

  • Global => It sets the "default" version, that means it can be used from anywhere. The file with all global versions can be found on ~/.tool-versions. e.g.: asdf global terraform 0.14.7

  • Local => It sets the version to be used only in the current folder. This has a high priority over the Global. The file with all local versions can be found on ${PWD}/.tool-versions. e.g.: asdf local terraform 0.13.0

  • Shell => It sets the version to be used only in the current shell session. This has a high priority over the Global and Local. There is no file, it sets an environment variable ASDF_<PLUGIN>_VERSION. e.g.: asdf shell terraform 0.12.29 If you don’t know what is an environment variable on Bash, check my post about it: https://www.lozanomatheus.com/post/bash-variables-things-that-you-probably-don-t-know-about-it

How to use

How to switch between version on Linux
Image by Kellysikkema on Unsplash

There are quite some quite options that can be used, these are just a few of them.

Updating asdf

It’s very simple to keep asdf update, all you need to do is to run one of the commands below.

## Get from the latest tag
asdf update
## or to get from the master branch
asdf update --head

Straight away

This is an example of how you can use asdf, from scratch (excluding the installation of asdf itself).

Switching between versions

Here is an example of how you can switch between versions of the same runtime.

My considerations

I start using asdf somewhere in 2017 for personal things and in production environments (CI/CD pipelines) since the end of 2019. It’s very stable, helps a lot when you need to have multiple versions of a tool, or just want to keep something updated. I start loving this tool when I start using it on CI/CD pipelines. Sometimes I had to use a different version or a specific version for a specific project. At that time, I was going to update the terraform code, it was just too much code to update all at once. With asdf, all I had to do is to create the file .tool-versions per project.

Also, because asdf uses the official packages and most of the plugins are using shell builtin commands, it makes it easier/stable to work with.

Read more

asdf website

asdf GitHub