Skip to main content
Toolsbase Logo

asdf Commands

Searchable asdf version manager reference. Covers plugin management, version switching, and environment setup with one-click copy.

Last updated:

How to Use

Expand how to use
  1. 1

    Search for commands

    Enter a command name in the search field, or filter by category (Plugin, Tools, Utils) to find the command you need.

  2. 2

    Review options and examples

    Check the command description, common options, and practical usage examples.

  3. 3

    Copy commands

    Click the copy button to copy the command to your clipboard for immediate use in your terminal.

asdf plugin add
Add a plugin

Common Options

  • <name>: Specify plugin name
  • <git-url>: Specify custom repository URL

Examples

asdf plugin add nodejs
Add the Node.js plugin
asdf plugin add python
Add the Python plugin
asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
Add a plugin from a custom URL

asdf plugin list
List installed plugins

Common Options

  • --urls: Show plugin repository URLs
  • --refs: Show Git reference information

Examples

asdf plugin list
Show installed plugins
asdf plugin list --urls
Show plugins with URLs

asdf plugin list all
List all available plugins

Common Options

  • Output: Plugin names and repository URLs

Examples

asdf plugin list all
Show all available plugins

asdf plugin remove
Remove a plugin and all its versions

Common Options

  • <name>: Specify plugin name to remove

Examples

asdf plugin remove nodejs
Remove the Node.js plugin
asdf plugin remove python
Remove the Python plugin

asdf plugin update
Update a plugin to the latest version

Common Options

  • <name>: Specify plugin name to update
  • <git-ref>: Update to a specific Git reference

Examples

asdf plugin update nodejs
Update the Node.js plugin
asdf plugin update python
Update the Python plugin

asdf plugin update --all
Update all plugins to their latest versions

Common Options

  • Batch update: Updates all installed plugins

Examples

asdf plugin update --all
Update all plugins at once

asdf install
Install a specific version

Common Options

  • <name> <version>: Specify plugin name and version
  • <name> latest: Install the latest stable version
  • No args: Install all versions from .tool-versions

Examples

asdf install nodejs 20.11.0
Install Node.js 20.11.0
asdf install nodejs latest
Install the latest stable Node.js
asdf install
Install all versions from .tool-versions

asdf uninstall
Uninstall a specific version

Common Options

  • <name> <version>: Specify plugin name and version

Examples

asdf uninstall nodejs 18.0.0
Uninstall Node.js 18.0.0
asdf uninstall python 3.9.0
Uninstall Python 3.9.0

asdf set
Set a tool version in .tool-versions

Common Options

  • <name> <versions...>: Specify plugin name and versions
  • -u: Update .tool-versions in the parent directory
  • -p: Update .tool-versions in the current directory only

Examples

asdf set nodejs 20.11.0
Set Node.js version in the current directory
asdf set -u nodejs 20.11.0
Update .tool-versions in the parent directory
asdf set python 3.12.0
Set the Python version

asdf current
Show currently active versions

Common Options

  • <name>: Show version for a specific plugin
  • No args: Show all current versions

Examples

asdf current
Show all current versions
asdf current nodejs
Show current Node.js version

asdf list
List installed versions

Common Options

  • <name>: Show versions for a specific plugin
  • <name> <version>: Filter versions

Examples

asdf list nodejs
Show installed Node.js versions
asdf list nodejs 20
Show only installed Node.js 20.x versions

asdf list all
List all available versions

Common Options

  • <name>: Specify plugin name
  • <version>: Filter versions

Examples

asdf list all nodejs
Show all available Node.js versions
asdf list all nodejs 20
Show only Node.js 20.x versions

asdf latest
Show the latest stable version

Common Options

  • <name>: Specify plugin name
  • --all: Show latest versions of all packages with install status

Examples

asdf latest nodejs
Show latest stable Node.js version
asdf latest --all
Show latest versions of all packages

asdf where
Show install path of a version

Common Options

  • <name> <version>: Specify plugin name and version
  • <name>: Show the current version's path

Examples

asdf where nodejs 20.11.0
Show Node.js 20.11.0 install path
asdf where python
Show current Python install path

asdf which
Show the path of an executable

Common Options

  • <command>: Specify the executable name

Examples

asdf which node
Show the path of the node executable
asdf which python
Show the path of the python executable

asdf help
Show documentation for a plugin and tool

Common Options

  • <name>: Specify plugin name
  • <version>: Show help for a specific version

Examples

asdf help nodejs
Show Node.js plugin documentation
asdf help python 3.12.0
Show Python 3.12.0 documentation

asdf exec
Execute a command shim for the current version

Common Options

  • <command>: Command to execute
  • [args...]: Arguments to pass to the command

Examples

asdf exec node --version
Check the current Node.js version
asdf exec python -c "print('hello')"
Run a command with the current Python

asdf env
Run a utility inside the shim execution environment

Common Options

  • <command>: Target command
  • [util]: Utility to run (default: env)

Examples

asdf env node
Show environment variables for the node shim
asdf env python which python
Run which inside the Python shim environment

asdf info
Show asdf system information (for debugging)

Common Options

  • Outputs OS, shell, asdf version, and plugin information

Examples

asdf info
Show asdf environment information

asdf version
Show the installed asdf version

Common Options

  • No args: Print the current asdf version

Examples

asdf version
Show the asdf version

asdf reshim
Regenerate shims

Common Options

  • <name> <version>: Specify plugin name and version

Examples

asdf reshim nodejs 20.11.0
Regenerate Node.js 20.11.0 shims
asdf reshim python 3.12.0
Regenerate shims for Python 3.12.0

asdf shimversions
List plugins and versions that provide a command

Common Options

  • <command>: Specify the command name

Examples

asdf shimversions node
Show which plugins/versions provide the node command
asdf shimversions python
Show which plugins/versions provide the python command

About asdf Commands

asdf Commands is a cheat sheet compiling essential asdf version manager commands. It covers plugin management, tool version setting (asdf set), and utility commands needed for development environment setup. Each command includes descriptions, common options, and practical examples that can be copied with one click.

Key Features

  • Collection of 22 essential asdf commands (v0.18.x)
  • Options and usage examples for each command
  • Category filtering (Plugin, Tools, Utils)
  • Real-time search functionality
  • One-click command copy

Use Cases

  • Looking up the asdf install / set command sequence when setting up a new Node.js or Python version for a project
  • Checking how to use asdf set before committing a .tool-versions file to a monorepo shared by the whole team
  • Referencing the asdf reshim command after running npm install -g or pip install to make new executables available in the shell
  • Onboarding a new developer by sharing a single .tool-versions file instead of documenting separate nvm, pyenv, and rbenv setup steps
  • Troubleshooting version conflicts on a CI server (GitHub Actions, CircleCI) by confirming the correct asdf install and plugin add commands

FAQ

How do I use asdf set?

asdf set writes a tool version to .tool-versions in the current directory. For example: asdf set nodejs 20.11.0. Use the -u flag to update .tool-versions in a parent directory, and -p to target only the current directory. The legacy asdf global, asdf local, and asdf shell commands were removed in v0.15 and replaced by asdf set.

Why do I need to run asdf reshim?

asdf routes commands through shim scripts. When you install a global CLI tool (npm install -g typescript, pip install black, gem install rubocop), asdf doesn't know about the new binary until you run asdf reshim to regenerate the shims.

Should I commit .tool-versions to my repo?

Yes. Committing .tool-versions means every developer who runs asdf install (no arguments) gets the exact same Node, Python, Ruby, and Go versions. It replaces the need to document version requirements in a README and eliminates 'works on my machine' version drift.

What's the difference between asdf where and asdf which?

asdf where nodejs 20.11.0 returns the installation directory (~/.asdf/installs/nodejs/20.11.0). asdf which node returns the full path to the active node executable. Use asdf which to debug PATH issues, and asdf where to find the installation root for manual inspection.

How do I install a specific Node.js or Python version with asdf?

Add the plugin first: asdf plugin add nodejs (or python). List available versions with asdf list all nodejs. Install with asdf install nodejs 20.11.0. Set the version with asdf set nodejs 20.11.0. The same pattern applies to every supported runtime.

What is the advantage of asdf over nvm, pyenv, or rbenv?

asdf manages every runtime — Node, Python, Ruby, Go, Java, Terraform, and hundreds more — with one tool and one .tool-versions file. Instead of remembering separate commands (nvm use, pyenv local, rbenv local), you use the same asdf set / install workflow for everything.

How do I update asdf itself?

Since v0.15, the asdf update command has been removed. Use your OS package manager (e.g., brew upgrade asdf on macOS, or apt upgrade on Linux) or download the latest binary from the asdf website.

Related Tools

mise Commandsuv CommandsDocker Commandskubectl Commands