asdf: how to manage python, java, and node all in one place

Among the many development tools, a version manager is one of the must-have tools. Instead of installing a separate version manager for each language, ASDF helps you manage multiple versions of almost any language with one tool. In this article, I'll explain what ASDF is and how to install it.

1. Why use a version manager?

When you start developing, the first thing you do is install the latest version of your language. More specifically, the compiler and runtime for that language. Then you install the editor and the package manager and start developing.

But then you run into a problem. The package I installed doesn't support the latest version. Dudun. I install an older version of the package because I really need it. I install it, but it doesn't work because I messed up the PATH settings, even for the latest version, which worked fine. As a developer, I'm not sure what to do.

This could have been avoided by installing the version manager first, then the language. As development environments become more complex, language versions become more important. It's not uncommon for certain packages not to support the current version properly, as in the example above, and there are many different environments for clients to consider.

Fortunately, language-specific version managers have been developed to do the heavy lifting for you. However, there are different types of version managers for different languages, and different ways to use them, so it can be exhausting to gather information before you even start development. It's even harder these days if you're developing in multiple languages at the same time. That's where the ASDF project comes in.

2. What is ASDF

The ASDF (opens in a new tab) is a platform that aggregates language version managers. After installing asdf, developers install the asdf plugin for the language they want to use. After proper installation, any language can be managed with a single API. There is no need to use different tools, different settings, and different methods for each language.

Let's say you're working on a project using React for the frontend and FastAPI for the backend. To set up your development environment, you'll first decide which version manager to use to install Nodejs: nvm, n, fnm, or volta. If you choose n, you'll need to spend some time installing, configuring, and learning how to use it.

Next is Python, and you'll go through the same thought process of setting up your development environment: pyenv, conda, mamba, etc.

Once you've installed asdf, you can install the Nodejs plugin and the Python plugin, set the versions as you would for any other language, and jump right into development.

It's that simple.

3. Advantages of asdf

In summary, ASDF is an all-in-one version manager that, once you get the hang of it, allows you to install and manage almost any language.

But that's not all. Most of ASDF's plugins are maintained by the community, so it supports a wide range of development tools. Gradle for JVM-based development, Deno for Nodejs, awscli and kubecli for infrastructure, and most other tools you might need are included as plugins.

Finally, ASDF allows you to set the version of a language or development tool per directory. The version you set is saved as a configuration file, which helps you and your teammates to use the exact same version. Language-specific plugins also support typical configuration files for each language. If your project contains common .env, .envrc or tool specific .nvmrc, .node-version or .rbenv files, you're covered by ASDF.

4. How to install asdf

asdf supports Linux and Mac OS only. For Windows users, you can install it using WSL2.

4.1. Installing asdf on Mac OS

To install asdf, you will need Curl and Git. These programs are installed by default on MacOS, but if you can't run them because of the xcrun error, see this post. There are two ways to install git and homebrew.

To install using git, type the following command in a terminal

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

If you are installing using Homebrew, type the following command in a terminal

brew install asdf

Once you've done this either way, the last thing you need to do is integrate it so that it works well in your shell. Depending on your shell, the commands you need to enter will be different, so check the official website guide (opens in a new tab) to find the combination you have installed and enter those commands.

Below is my example. I used Fish shell and Homebrew.

As shown below, if you don't get any error messages, the installation went well.

Now verify the installation by running the verify version command. Please go to Section 5 to see the process from plugin installation onwards.

4.2. How to install asdf on Windows

Open a shell in WSL to install asdf.

If you are using the latest version of Windows, you are using WSL2. I am running Windows on Mac OS Parallels and WSL2 is currently blocked, so I proceeded with WSL version 1.

If you don't already have WSL installed, go to the Microsoft Store: Windows Subsystem for Linux page (opens in a new tab) and install it, Download Ubuntu from the Microsoft Store: Ubuntu (opens in a new tab). Other Linux distributions are also available.

Run the installed Ubuntu and a Bash shell will be waiting for you. Run the following command to install ASDF

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

Result:

Once this is done, add the following two lines to the bottom of your ~/.bashrc file. These are the steps to enable ASDF in the shell.

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

Screenshot of the addition using the Vim editor:

Now reboot Ubuntu and check the ASDF version.

5. How to use ASDF

Let's see how to use ASDF by installing the NodeJS plugin and upgrading to the latest version. It works the same on Mac and Windows, and I'll do it on Mac.

The asdf plugin is maintained on Github, You can see the list of plugins available for installation at a glance in the asdf-vm/asdf-plugins repo (opens in a new tab).

The command to install the nodejs plugin is shown below.

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

Result of execution:

After installing the plugin, it will give you a list of all the nodejs available for download, and there are tons of versions. Install the latest one. Run asdf install [plugin_name] [version_name] to install it. This is what it looks like after installation.

Let's use the installed version in the current shell.

You can also make it available in the current directory or throughout the operating system, depending on the commands in asdf.

6. Conclusion

So far we've seen how to install asdf for each OS and a brief walkthrough of how to use it. For a more detailed walkthrough, I'll be back with a post that covers setting up a development environment for each language.

Personally, I'm very curious about development tools, and I think I've tried every popular release manager for every language I've used. I don't usually trust one-size-fits-all tools, but I've been using ASDF for a while now without any problems. I highly recommend it to anyone who regularly develops for multiple platforms and in multiple languages.