asdf

asdf is a free, open-source tool version manager for Linux and macOS. It gives project teams one command interface and a shared `.tool-versions` file for selecting versions of multiple tools and runtimes. Plugins let asdf manage tools such as Node.js, Ruby, and Elixir, and the plugin API allows support for more tools. When a command runs, asdf searches for `.tool-versions` beginning in the current directory and moving toward the home directory. It uses shims to launch the executable at the selected version. Existing files such as `.ruby-version`, `.nvmrc`, and `.node-version` can be supported on a per-plugin basis. The listed shell support includes Bash, ZSH, Fish, and Elvish, with completions available. A GitHub Action can use `.tool-versions` in CI/CD workflows. Installation routes include Homebrew, Zypper, Pacman, precompiled binaries, Go, and a source build. asdf manages tool versions, not system packages or upstream dependencies. If no version is listed for a tool, running it produces an error unless its version is set to `system`.

asdf provides a shared, plugin-based way to select tool versions across project work. It is not a system package manager, and tools need a selected version or the `system` setting to run.

asdf suits project teams that want to coordinate tool and runtime versions through a shared configuration file. It is intended for users working on Linux or macOS who need version management across multiple tools.

asdf is a free, open-source version manager for developers and project teams working across multiple tools and runtimes. It is strongest when a team wants a shared version convention; look elsewhere if you need system-package or upstream-dependency management.

Overview

asdf puts supported tools behind one command interface and a shared .tool-versions file. That gives a project team a consistent way to specify tool versions, rather than maintaining separate configuration conventions for each runtime. The approach is useful across ecosystems, but its reach depends on plugin support for the tools a project uses.

This is a focused version manager, not a complete development environment manager. It does not manage system packages or upstream dependencies, so teams need other solutions for those jobs.

Key features

Project-based version selection

asdf searches for .tool-versions from the current directory upward toward the home directory. Shims for installed executables then run the version selected for the active project. This makes the project’s location an important part of version selection, and teams can share the expected versions through the project file.

There is a sharp configuration edge: if a tool has no version set, running it produces an error unless the version is set to system. Developers who expect an unset tool to fall back automatically will need to adjust their workflow.

Plugins and migration

Plugins let asdf manage tools such as Node.js, Ruby, and Elixir, while its plugin API permits support for more tools. This unified interface can reduce the need for a different version-selection workflow for every ecosystem, though it is only as useful as the plugins available for a team’s toolset.

Per-plugin support for existing files such as .ruby-version, .nvmrc, and .node-version can ease migration. Because that support is plugin-specific, teams should not assume every existing version file will work uniformly.

Shell and CI support

asdf supports Bash, ZSH, Fish, and Elvish, with completions available. Its GitHub Action can use .tool-versions in CI/CD workflows, making the same version declaration useful beyond local development.

Installation and scope

Installation options include Homebrew, Zypper, Pacman, precompiled binaries, Go, and a source build. The installation guidance covers Linux and macOS dependencies and provides binaries for operating-system and architecture combinations. The stated platforms are Linux and macOS.

asdf manages tool versions, not the tools’ upstream dependencies or system packages. It is therefore a good fit for aligning runtime and tool versions, but not for replacing a package manager or dependency-management workflow.

Pricing

asdf is free and open source. The free plan costs nothing and covers its open-source tool-version-management offering; there are no paid plans listed and no free trial. That makes it a straightforward choice for teams seeking version management without a subscription, though the scope remains limited to tool versions.

Platforms

asdf supports Linux and macOS. Developers on other platforms should consider an alternative with stated support for their operating system.

Who it's for

asdf suits project teams that want to commit one version file and give developers a shared way to select tools across multiple runtimes. It is especially relevant when a project spans ecosystems such as Node.js, Ruby, and Elixir and plugin coverage meets the team’s needs. It is a weaker fit for anyone seeking package installation, dependency resolution, or version fallback when a tool has not been configured.

Pros and cons

Pros

• One shared version file: teams can specify expected tool versions for a project in .tool-versions.
• One interface across supported tools: plugins cover examples including Node.js, Ruby, and Elixir, and the plugin API can extend support.
• Useful workflow compatibility: per-plugin migration support covers several existing version-file formats, and a GitHub Action can use the shared file in CI/CD.
• No subscription cost: the open-source tool is free, with no paid plans listed.

Cons

• Not a package or dependency manager: system packages and upstream dependencies require other tools.
• Unset versions stop execution: a tool without a configured version errors unless set to system.
• Plugin-dependent coverage: support for a team’s tools and legacy version files depends on the relevant plugins.
• Linux and macOS only: those are the supported platforms stated for asdf.

Alternatives

For a directory of comparable tools, browse Runtime Version Managers, Development Environment Management Tools, or Development Environment Managers.

• rustup is a free option with Linux, macOS, and Windows support.
• PHPBrew is a free alternative, but building PHP requires development packages and unsupported older PHP versions may fail to build.
• elan is a free Lean version manager for Linux, macOS, and Windows, under Apache-2.0 and MIT licenses.
• fnm is a free option with Linux, macOS, and Windows support.
• goenv is a free Go version manager for Linux and macOS.
• GVM is a free, MIT-licensed Go version manager for Linux and macOS.
• mise is a free, MIT-licensed option for macOS, Linux, and Windows.
• nodenv is a free Node.js version manager for Unix-like systems.

Verdict

Choose asdf if your team wants a free, shared way to select tool versions across projects and its plugins cover your stack. Its central advantage is the common .tool-versions workflow; its main limitation is that it neither manages dependencies nor tolerates an unset tool version without an explicit system setting.