asdf

List all available plugins

$ asdf plugin list all

$ asdf plugin add [name]

$ asdf list all [name]

$ asdf install [name] [version]

$ asdf set -u [name] [version]

$ asdf set [name] [version]

$ asdf current [name]

asdf [command] [args...]

install [version]
    Installs a specific version of a tool. If no version is specified, it installs the version found in the .tool-versions file or the globally configured version.

local
    Sets the local tool version for the current directory by creating or updating a .tool-versions file. This version takes precedence over global settings.

global
    Sets the global tool version for your user. This version is used if no local .tool-versions file is present.

uninstall
    Removes an installed version of a tool from your system.

list []
    Lists all installed versions of a specific tool, or all tools if no tool is specified.

list all
    Lists all available versions of a tool that can be installed via its plugin.

current []
    Displays the currently active version of a tool based on the .tool-versions file or global configuration.

plugin add [git-url]
    Adds a new plugin for a specific tool. Plugins are typically found in the asdf-plugins GitHub organization or provided by third parties.

plugin list
    Lists all installed plugins.

plugin update []
    Updates a specific plugin, or all installed plugins if no name is provided.

reshim
    Rebuilds the shims (executable wrappers) for all installed tools. This is often needed after installing new executables with a language (e.g., Ruby gems, Node.js npm packages).

update
    Updates asdf itself to the latest version.

help []
    Displays help information for asdf or a specific subcommand.

asdf is an extensible command-line tool that allows you to manage multiple versions of various programming language runtimes (such as Node.js, Ruby, Python, Elixir, Go, and more) on a per-project or global basis. It operates through a robust plugin system, where each language or tool has its own plugin responsible for installing and managing different versions. This architecture makes asdf highly flexible and agnostic to the specific runtime.

It uses a .tool-versions file, typically located in a project's root directory, to declare the exact versions of tools required for that project. This ensures consistency across development environments and teams. asdf works by inserting 'shims' into your system's PATH, which are small scripts that intelligently execute the correct version of a tool based on your project's configuration or global settings, without polluting your system with multiple binaries directly. It's designed to be lightweight, easy to use, and helps maintain a clean and organized development environment.

asdf requires proper shell integration (e.g., sourcing asdf.sh or asdf.fish in your shell configuration) to function correctly. It relies on its plugin system, meaning each tool needs a corresponding plugin, and some plugins might have their own system dependencies (e.g., build tools, compilers). While asdf manages versions, it is not a full-fledged package manager for system-wide dependencies.

The core of asdf's flexibility lies in its plugin system. Each language or tool supported by asdf has a corresponding plugin, which is typically a Git repository containing scripts for installing, listing, and uninstalling versions of that specific tool. Users can add new plugins from GitHub, allowing asdf to support virtually any command-line tool or runtime.

This file is central to asdf's per-project version management. When you navigate into a directory, asdf scans for a .tool-versions file in the current directory or its parent directories. This file explicitly lists the desired versions for one or more tools (e.g., 'nodejs 16.14.0', 'ruby 3.1.2'), ensuring that every developer working on a project uses the exact same tool versions, which helps prevent 'it works on my machine' issues.

asdf-vm was developed by Halit Narin and first gained prominence around 2017. Its creation was driven by a desire for a single, generic version manager that could handle multiple language runtimes, addressing the fragmentation of language-specific tools like nvm, rvm, and pyenv. By abstracting the version management logic into a core tool and externalizing language support via a robust plugin system, asdf offered a highly flexible and extensible solution that quickly gained adoption in the developer community.

nvm(1), rvm(1), pyenv(1), chruby(1), direnv(1)