Managing Node.js, Python, and Go with asdf-vm: Goodbye Version Manager Mess – ITFROMZERO

Table of Contents

Background: When “Version Hell” Is No Longer Just a Rumor

Developers often find themselves in “laughing through the tears” situations regarding software versions. Project A needs Node.js v14, while Project B requires v18. Meanwhile, an old Python script only runs on version 3.7, but you need 3.11 for a new feature.

Back when I was a sysadmin, I once lost an entire afternoon just debugging environment errors. The application wouldn’t run because I forgot to switch Ruby versions before deploying. At that time, my machine was a “mixed hotpot”: nvm for Node, pyenv for Python, rbenv for Ruby. The .zshrc file bloated to over 100 lines just to load these managers, making shell startup incredibly slow.

asdf-vm emerged as a lifesaver. Instead of installing 5-7 separate tools, you only need one single framework. It works on a plugin mechanism. Whether you need a language, or even Terraform or Kubectl, you just add that plugin. One syntax, one workflow for everything.

Installing asdf-vm on Linux

To start, we need a clean environment. asdf runs smoothly on Ubuntu, Debian, Fedora, and Arch Linux.

Step 1: Install Necessary Dependencies

Your machine needs git and curl ready before pulling asdf. For Ubuntu or Debian, run the following command:

sudo apt update
sudo apt install curl git -y

Step 2: Download asdf

The best way is to clone directly from the GitHub repo for easy updates. Currently, v0.14.0 is the stable version. You can check the latest tags on their homepage.

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

Step 3: Shell Configuration (Bash/Zsh)

This is a crucial step. Without shell configuration, the asdf command will result in “command not found”.

For Bash users (default on Ubuntu), paste this into your ~/.bashrc file:

echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
source ~/.bashrc

If you use Zsh, add this to your ~/.zshrc file:

echo '. "$HOME/.asdf/asdf.sh"' >> ~/.zshrc
source ~/.zshrc

Practical Configuration: Managing Node.js, Python, and Go

The power of asdf lies in its system of over 500 plugins. By default, asdf is like an empty skeleton. You need to “teach” it how to handle each specific language.

Installing Plugins

Each language requires its own plugin. Let’s start with the three most popular ones in the dev world today:

# Add plugin for Node.js
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

# Add plugin for Python
asdf plugin add python

# Add plugin for Go
asdf plugin add golang

Installing Specific Versions

Once the plugin is installed, installing a version takes only seconds. For example, with Node.js:

# List all installable Node.js versions
asdf list all nodejs

# Install the latest LTS version
asdf install nodejs lts

# Install specific versions for each project
asdf install nodejs 18.16.0
asdf install python 3.10.11
asdf install golang 1.20.4

Pro tip: asdf builds Python from source code. If your machine lacks libraries like libssl-dev, the installation will error out. Don’t worry, just install the additional system packages according to the error log and run it again.

Setting Global and Local Versions

This is the most valuable feature. asdf allows you to define a default version for the entire machine or specifically for each directory.

Global Setup: Use this when you want a version to appear everywhere.

asdf global nodejs 18.16.0
asdf global python 3.10.11

Local Setup: Suppose your old project requires Node v14. Navigate to that directory and type:

cd ~/my-old-project
asdf local nodejs 14.21.3

At this point, asdf automatically creates a .tool-versions file. Here’s where the magic happens: whenever you cd into this directory, Node.js will automatically switch to v14. Exit the directory, and it reverts to v18. You no longer need to worry about manual switching.

Checking and Optimizing Workflow

To check the current status of the system, use the command:

asdf current

The screen will list exactly which version is running and its source (from a global or local file).

Plugin Maintenance

The community updates plugins very frequently to support security patches. You can refresh everything with a single command:

asdf plugin update --all

If you no longer need a language, remove it to clean up storage:

asdf plugin remove golang

Pro-tip for Teamwork

Commit the .tool-versions file to Git. When colleagues clone the code, they just need to type asdf install to get the exact same environment as you. No more “it works on my machine” arguments.

Using asdf is like tidying up a messy desk. It helps you focus on writing code instead of struggling with configuration. If you’re tired of managing nvm or pyenv, try asdf today.