How to Install and Use asdf in Linux to Manage Multiple Programming Language Runtimes

Modern software development often demands switching across multiple runtime versions of Node.js, Python, Ruby, Go, and Java depending on repository specifications. While dedicated version managers such as nvm, pyenv, and rbenv function reliably for individual languages, maintaining separate CLI utilities leads to fragmented shell startup scripts and conflicting environment variables. The asdf extensible version manager unifies language environment management through a single modular CLI framework backed by lightweight plugins and directory-specific configuration files.

Prerequisites and Dependency Installation

Before installing asdf, your Linux distribution requires basic developer utilities including git, curl, and archive extraction libraries. Depending on the runtime plugins you intend to compile, building languages from source also necessitates standard build toolchains.

Install prerequisite packages across common distributions using your system package manager:

# Debian / Ubuntu / Linux Mint
sudo apt update
sudo apt install -y curl git build-essential libssl-dev zlib1g-dev

# Fedora / RHEL / AlmaLinux
sudo dnf install -y curl git gcc gcc-c++ make openssl-devel zlib-devel

# Arch Linux / Manjaro
sudo pacman -Sy --noconfirm curl git base-devel

Cloning and Initialising asdf

The recommended installation method clones the official release branch of asdf into a hidden home directory repository (~/.asdf) and hooks into your shell configuration.

# Clone the latest stable branch
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

Configure shell integration by appending the asdf binary path and shell autocompletions to your profile file. Select the command appropriate for your default shell:

# For Bash users (~/.bashrc)
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
source ~/.bashrc

# For Zsh users (~/.zshrc)
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.zshrc
echo 'fpath=(${ASDF_DIR}/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

Verify that your shell detects the utility by checking the installed version:

asdf --version

Managing Plugins for Language Runtimes

The core asdf engine does not bundle language compilers directly. Instead, community-maintained plugins provide the download, build, and shim-binding instructions for specific programming languages and tools.

# List all available official community plugins
asdf plugin list all

# Add plugins for Node.js and Python
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf plugin add python https://github.com/danhper/asdf-python.git

# List currently installed plugins
asdf plugin list

To update all installed plugins to their latest repository commits, run:

asdf plugin update --all

Installing and Listing Runtime Versions

Once a plugin is registered, query the available upstream releases and compile the exact versions required for your workflows:

# View all available upstream releases for Node.js
asdf list all nodejs

# Filter for LTS or recent major versions
asdf list all nodejs | grep "^20\\." | tail -n 5

# Install specific versions of Node.js and Python
asdf install nodejs 20.18.0
asdf install python 3.12.7

Review installed runtime binaries stored inside your local ~/.asdf/installs/ directory:

asdf list

Setting Global and Local Directory Versions

The true power of asdf lies in its hierarchical version resolution mechanism. You can establish a fallback global baseline and override it on a per-project basis.

# Set a global default version across all terminal sessions
asdf global nodejs 20.18.0
asdf global python 3.12.7

# Verify current active versions and shim resolution
node --version
python --version

When working within a specific project repository, create a directory-level configuration file named .tool-versions:

# Navigate to your project directory
cd ~/projects/legacy-app

# Set a local version override
asdf local nodejs 18.20.4

# Check active runtime versions in current working tree
asdf current

The resulting .tool-versions text file can be committed directly to Git, enabling every team member running asdf to automatically synchronise their exact runtime environments by simply executing asdf install inside the repository root.

Command Reference and Workflow Comparison

The following table outlines standard operational commands for day-to-day runtime maintenance:

Command	Operational Purpose	Configuration Scope
asdf plugin add <name>	Registers a new language or runtime plugin	System-wide (~/.asdf/plugins/)
asdf install <name> <ver>	Downloads and compiles specified version	System-wide (~/.asdf/installs/)
asdf global <name> <ver>	Sets user-level fallback version in ~/.tool-versions	User home directory
asdf local <name> <ver>	Creates or updates local .tool-versions	Current directory and subfolders
asdf current	Displays resolved versions in active shell context	Terminal session stdout
asdf reshim <name>	Regenerates executable shims after installing global CLI packages	Shim layer (~/.asdf/shims/)
asdf uninstall <name> <ver>	Purges an unused runtime build to reclaim disk space	Disk storage

Whenever you install global command-line utilities using package managers like npm install -g yarn or pip install --user ruff, execute asdf reshim to generate execution wrappers so the shell immediately resolves the new binaries.