asdf Cheat Sheet

Overview

asdf is a universal version manager that replaces language-specific tools like nvm, pyenv, rbenv, and rustup with a single CLI. It uses a plugin system to support virtually any language or tool, and manages versions through simple .tool-versions files that can be committed to repositories for team consistency.

asdf supports global, local (per-directory), and shell-level version settings. Its plugin ecosystem covers hundreds of tools including Node.js, Python, Ruby, Go, Rust, Java, Terraform, kubectl, and many more. Version resolution walks up the directory tree, making it easy to manage different versions across projects.

Installation

# macOS
brew install asdf

# Linux (git clone)
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

# Add to shell (bash)
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc

# Add to shell (zsh)
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.zshrc

# Add to shell (fish)
echo 'source ~/.asdf/asdf.fish' >> ~/.config/fish/config.fish

# If installed via Homebrew (bash)
echo '. "$(brew --prefix asdf)/libexec/asdf.sh"' >> ~/.bashrc

# Reload shell
source ~/.bashrc

Core Commands

Command	Description
asdf plugin add <name>	Install a plugin
asdf plugin list	List installed plugins
asdf plugin list all	List all available plugins
asdf plugin update --all	Update all plugins
asdf install <name> <ver>	Install a specific version
asdf install <name> latest	Install latest stable version
asdf list <name>	List installed versions
asdf list all <name>	List all available versions
asdf global <name> <ver>	Set global version
asdf local <name> <ver>	Set local (directory) version
asdf shell <name> <ver>	Set version for current shell
asdf current	Show current versions
asdf uninstall <name> <ver>	Remove a version
asdf where <name> <ver>	Show install path
asdf which <cmd>	Show path to command shim

Plugin Management

# Add common plugins
asdf plugin add nodejs
asdf plugin add python
asdf plugin add ruby
asdf plugin add golang
asdf plugin add rust
asdf plugin add java
asdf plugin add terraform
asdf plugin add kubectl

# Add plugin from custom URL
asdf plugin add mycli https://github.com/user/asdf-mycli.git

# Update a specific plugin
asdf plugin update nodejs

# Update all plugins
asdf plugin update --all

# Remove a plugin
asdf plugin remove nodejs

# List installed plugins
asdf plugin list

# List all available plugins
asdf plugin list all | grep terraform

Version Management

Installing Versions

# Install specific version
asdf install nodejs 20.11.0
asdf install python 3.12.1

# Install latest stable
asdf install nodejs latest
asdf install python latest

# Install latest matching prefix
asdf install nodejs latest:20

# Install all versions from .tool-versions
asdf install

Setting Versions

# Set global default
asdf global nodejs 20.11.0
asdf global python 3.12.1

# Set local (creates .tool-versions in current dir)
asdf local nodejs 18.19.0
asdf local python 3.11.7

# Set for current shell session only
asdf shell nodejs 16.20.2

# Show current versions
asdf current
asdf current nodejs

# Unset shell version
asdf shell nodejs --unset

.tool-versions File

# .tool-versions (committed to repo)
nodejs 20.11.0
python 3.12.1
ruby 3.3.0
golang 1.22.0
terraform 1.7.0

# Multiple versions (first is default)
python 3.12.1 3.11.7

# Use system version
nodejs system

Configuration

.asdfrc Settings

# ~/.asdfrc
# Use legacy version files (.nvmrc, .python-version, etc.)
legacy_version_file = yes

# Don't prompt for plugin add confirmation
plugin_repository_last_check_duration = never

Environment Variables

# Custom install location
export ASDF_DIR="$HOME/.asdf"
export ASDF_DATA_DIR="$HOME/.asdf"

# Default tool versions file name
export ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=".tool-versions"

# Concurrency for builds
export ASDF_CONCURRENCY=4

# Plugin-specific variables
export ASDF_NODEJS_LEGACY_FILE_DYNAMIC_STRATEGY=latest_installed
export ASDF_PYTHON_DEFAULT_PACKAGES_FILE="$HOME/.default-python-packages"

Default Packages

# ~/.default-npm-packages (auto-installed with each Node version)
yarn
typescript
ts-node
prettier
eslint

# ~/.default-python-packages
pip
setuptools
wheel
pipx
black
ruff

# ~/.default-gems
bundler
rails
solargraph

Advanced Usage

Legacy Version File Support

# Enable in ~/.asdfrc
legacy_version_file = yes

# Now asdf reads:
# .nvmrc / .node-version for Node.js
# .python-version for Python
# .ruby-version for Ruby
# .java-version for Java
# .terraform-version for Terraform

Reshimming

# Reshim after installing global packages
asdf reshim nodejs
asdf reshim python

# Example: after npm install -g
npm install -g typescript
asdf reshim nodejs

Version Resolution Order

# asdf resolves versions in this order:
# 1. ASDF_<TOOL>_VERSION environment variable
# 2. .tool-versions in current directory
# 3. .tool-versions in parent directories (walking up)
# 4. $HOME/.tool-versions (global)

# Check which .tool-versions file is being used
asdf where nodejs
asdf current nodejs

Batch Operations

# Install all tools from .tool-versions
asdf install

# Update all plugins and install latest versions
asdf plugin update --all
for plugin in $(asdf plugin list); do
  asdf install "$plugin" latest
  asdf global "$plugin" latest
done

# Clean old versions
asdf list nodejs
asdf uninstall nodejs 16.20.0
asdf uninstall nodejs 18.17.0

Troubleshooting

Issue	Solution
Command not found after install	Run asdf reshim <plugin>
Version not available	Run asdf plugin update <plugin> then retry
Build failures (Python/Ruby)	Install build deps: build-essential libssl-dev libffi-dev
.tool-versions ignored	Check asdf current and file location
Legacy version file not read	Set legacy_version_file = yes in ~/.asdfrc
Slow plugin list all	Plugin repos are cached; run asdf plugin update

# Debug version resolution
asdf current
asdf where nodejs
asdf which node

# Check shim paths
ls ~/.asdf/shims/

# Verify plugin health
asdf plugin list --urls

# Full reinstall of a version
asdf uninstall nodejs 20.11.0
asdf install nodejs 20.11.0
asdf reshim nodejs