https://asdf-vm.com/guide/introduction.html

asdf
Getting Started
ReferenceReference

  * Manage

      + Core
      + Plugins
      + Versions
      + Configuration
      + All Commands
      + Changelog open in new window

PluginsPlugins

  * Author

      + Create a Plugin
      + GitHub Plugin Template open in new window
  * First Party Plugins

      + Elixir open in new window
      + Erlang open in new window
      + Node.js open in new window
      + Ruby open in new window
  * Community Plugins

      + asdf-community open in new window
      + GitHub Topics Search open in new window
  * Reference

      + Plugin Shortname Index open in new window

ContributeContribute

  * Core

      + asdf
      + Docs & Site
  * Plugins

      + First-Party Plugins
  * CICD

      + GitHub Actions

Learn MoreLearn More

  * Questions

      + FAQ
      + GitHub Issues open in new window
      + StackOverflow Tag open in new window
  * Resources

      + Thanks

LanguagesLanguages

  * English
  * Brazilian Portuguese
  * Jian Ti Zhong Wen 

GitHub open in new window
[                    ]
Getting Started
ReferenceReference

  * Manage

      + Core
      + Plugins
      + Versions
      + Configuration
      + All Commands
      + Changelog open in new window

PluginsPlugins

  * Author

      + Create a Plugin
      + GitHub Plugin Template open in new window
  * First Party Plugins

      + Elixir open in new window
      + Erlang open in new window
      + Node.js open in new window
      + Ruby open in new window
  * Community Plugins

      + asdf-community open in new window
      + GitHub Topics Search open in new window
  * Reference

      + Plugin Shortname Index open in new window

ContributeContribute

  * Core

      + asdf
      + Docs & Site
  * Plugins

      + First-Party Plugins
  * CICD

      + GitHub Actions

Learn MoreLearn More

  * Questions

      + FAQ
      + GitHub Issues open in new window
      + StackOverflow Tag open in new window
  * Resources

      + Thanks

LanguagesLanguages

  * English
  * Brazilian Portuguese
  * Jian Ti Zhong Wen 

GitHub open in new window

  * Introduction
      + How It Works
      + Related Projects
          o nvm / n / rbenv etc
          o direnv
          o Homebrew
          o NixOS
      + Why use asdf?
  * Getting Started

# Introduction

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 set up 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.

# Related Projects

# 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
its 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 its own programming
language, many CLI tools and a package 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 its versions with asdf, does not mean that is the best
course of action for that specific tool.

Edit this page open in new window
Last Updated:
Contributors: James Hegedus, Sebastian Nadorp

Getting Started