asdf Version Manager Skill

asdf is a universal CLI version manager — one tool to replace nvm, pyenv, rbenv, tfenv, goenv and more. It manages per-project versions via .tool-versions files and switches versions automatically as you navigate directories.

When to Use This Skill

Use this skill when the user is:

• Installing or setting up asdf on a new machine (any OS, any shell)
• Adding plugins for a language or tool (Node.js, Python, Go, Terraform, kubectl, Helm, etc.)
• Installing or switching versions of any tool managed by asdf
• Managing .tool-versions files — creating, editing, or understanding version resolution
• Migrating from single-language version managers like nvm, pyenv, rbenv, goenv, tfenv, or sdkman
• Configuring shell integration for Bash, Zsh, Fish, or Elvish
• Debugging version resolution — wrong version active, shims not working, command not found errors
• Onboarding to a project that uses .tool-versions for reproducible environments
• Setting up CI/CD pipelines that need deterministic tool versions via asdf
• Configuring .asdfrc for legacy file support, concurrency, or plugin repository settings

Core Concepts

• Plugin: Adapter for a specific tool (nodejs, python, terraform, kubectl, etc.)
• Tool: The actual runtime/binary managed (e.g., Node.js 20.11.0)
• .tool-versions: Project-level file declaring exact versions; asdf resolves it by traversing up the directory tree to $HOME
• Shims: Lightweight wrappers in ~/.asdf/shims/ that intercept tool invocations and dispatch to the right version
• Version scopes: project (.tool-versions in cwd) → parent dirs → $HOME/.tool-versions → env var ASDF_${TOOL}_VERSION

Installation

Dependencies (all platforms)

# Debian/Ubuntu
sudo apt install -y git curl

# macOS
brew install git curl

Install asdf binary (recommended: binary download)

# Download latest release from https://github.com/asdf-vm/asdf/releases
# Or via git clone (classic method):
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.16.7

Shell Configuration

Fish shell (Jean-Jacques' setup):

# Add to ~/.config/fish/config.fish
source ~/.asdf/asdf.fish

# Install completions
mkdir -p ~/.config/fish/completions
ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions/asdf.fish

Bash:

# Add to ~/.bashrc or ~/.bash_profile
. "$HOME/.asdf/asdf.sh"
. "$HOME/.asdf/completions/asdf.bash"

Zsh:

# Add to ~/.zshrc
. "$HOME/.asdf/asdf.sh"

After configuration, restart shell or source the config file.

Essential Commands

Plugin Management

asdf plugin list all              # Browse all available plugins
asdf plugin list all | grep terra # Search for specific plugins
asdf plugin add nodejs            # Add plugin by shortname (from registry)
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git  # Add by URL
asdf plugin list                  # List installed plugins
asdf plugin update nodejs         # Update a plugin
asdf plugin update --all          # Update all plugins
asdf plugin remove nodejs         # Remove plugin + all its installs

Version Management

asdf list all nodejs              # List all installable versions
asdf list all nodejs 20           # List versions matching prefix
asdf install nodejs latest        # Install latest version
asdf install nodejs 20.11.0       # Install specific version
asdf install                      # Install all versions in .tool-versions
asdf list nodejs                  # List installed versions
asdf uninstall nodejs 18.0.0      # Remove a version

Setting Versions

asdf set nodejs 20.11.0           # Set version in ./.tool-versions (project)
asdf set -u nodejs 20.11.0        # Set version in ~/.tool-versions (global/user default)
asdf set -p nodejs 20.11.0        # Set in nearest parent .tool-versions
asdf set nodejs latest            # Resolve and write latest version
asdf current                      # Show active version for all tools in cwd
asdf current nodejs               # Show active version for one tool
asdf where nodejs                 # Show install path for active version
asdf which node                   # Show shim path for a command

Note: asdf set replaced the older asdf local / asdf global commands in asdf v0.15+. Both still work but asdf set is the modern API.

Environment Variable Override

# Temporarily override without editing .tool-versions
ASDF_NODEJS_VERSION=18.0.0 node --version

.tool-versions Format

nodejs 20.11.0
python 3.12.2
terraform 1.7.4
kubectl 1.29.2
golang 1.22.1

• One tool per line, <name> <version>
• Multiple versions separated by spaces (fallback chain): python 3.12.2 2.7.18
• Special keywords: system (use OS-installed version), path:~/my/custom/build
• Commit to version control — this is the contract for the project's tool versions

.asdfrc Configuration

Located at ~/.asdfrc:

# Support .nvmrc, .ruby-version, etc. (per-plugin support required)
legacy_version_file = yes

# Keep downloaded archives (useful for slow connections)
always_keep_download = no

# Concurrency for parallel installs
concurrency = auto

# Plugin repository refresh interval in minutes
plugin_repository_last_check_duration = 60

Common Plugins for DevOps/Cloud (Jean-Jacques' stack)

Many plugins may require system dependencies — always check the plugin's README before installing.

Migration from Other Version Managers

Enable legacy file support in ~/.asdfrc:

legacy_version_file = yes

Troubleshooting

Shims not working / command not found

asdf reshim nodejs          # Regenerate shims for a plugin
asdf reshim                 # Regenerate all shims
echo $PATH                  # Verify ~/.asdf/shims is early in PATH
type -a node                # Fish: check which binary is resolved

Version not being picked up

asdf current                # See what version is resolved and from where
# Look for "No version set" warnings
# Check .tool-versions exists in project dir or a parent

Plugin install failures

• Check plugin README for system dependency requirements
• Ensure git is installed and accessible
• For nodejs: may need gnupg for keyring verification

Data directory

Default: ~/.asdf/ — override with export ASDF_DATA_DIR=/custom/path in shell config.

Typical Project Onboarding Workflow

# 1. Clone project
git clone <repo> && cd <repo>

# 2. Add plugins for each tool in .tool-versions (if not already added)
asdf plugin add nodejs
asdf plugin add python

# 3. Install all versions specified in .tool-versions
asdf install

# 4. Verify
asdf current

Reference

• Full docs: https://asdf-vm.com/
• Plugin list: https://github.com/asdf-vm/asdf-plugins
• All commands: asdf --help or asdf <command> --help