Introduction

Hi, we've recently migrated our docs and added some new pages. If you would like to help translate this page, see the "Edit this page" link at the bottom of the page.

asdf is a tool version manager. All tool version definitions are contained within one file (.tool-versions) which you can check-in to your project's Git repository to share with your team, ensuring everyone is using the exact same versions of tools.

The old way of working required multiple CLI version managers, each with their distinct API, configurations files and implementation (e.g. $PATH manipulation, shims, environment variables, etc...). asdf provides a single interface and configuration file to simplify development workflows, and can be extended to all tools and runtimes via a simple plugin interface.

How It Works

Once asdf core is setup with your Shell configuration, plugins are installed to manage particular tools. When a tool is installed by a plugin, the executables that are installed have shimsopen in new window created for each of them. When you try and run one of these executables, the shim is run instead, allowing asdf to identify which version of the tool is set in .tool-versions and execute that version.

nvm / n / rbenv etc

Tools like nvmopen in new window, nopen in new window and rbenvopen in new window are all written as Shell scripts which create shims for the executables installed by these tools.

asdf is very similar and was built to compete in this space of tool/runtime version management. The differentiating factor for asdf is it's plugin system which removes the need for a manager per tool/runtime, different commands per manager and different *-version files in your repo.

direnv

augments existing shells with a new feature that can load and unload environment variables depending on the current directory.

asdf does not manage Environment Variables, however there is a plugin asdf-direnvopen in new window to integrate direnv behaviour with asdf.

See direnv docsopen in new window for more.

Homebrew

The Missing Package Manager for macOS (or Linux)

Homebrew manages your packages and their upstream dependencies. asdf does not manage upstream dependencies, it is not a package manager, that burden is upon the user, though we try and keep the dependency list small.

See Homebrew docsopen in new window for more.

NixOS

Nix is a tool that takes a unique approach to package management and system configuration

NixOS aims to build truly reproducible environments by managing exact versions of packages up the entire dependency tree of each tool, something asdf does not do. NixOS does this with it's own programming language, many CLI tools and a pacakges collection of over 60,000 packages.

Again asdf does not manage upstream dependencies and is not a package manager.

See NixOS docsopen in new window for more.

Why use asdf?

asdf ensures teams are using the exact same versions of tools, with support for many tools via a plugin system, and the simplicity and familiarity of being a single Shell script you include in your Shell config.

Note

asdf is not intended to be a system package manager. It is a tool version manager. Just because you can create a plugin for any tool and manage it's versions with asdf, does not mean that is the best course of action for that specific tool.