asdf Documentation

Extendable version manager with support for Ruby, Node.js, Elixir, Erlang & more

25,519 stars Go Go 1 file ยท ~14,218 tokens #asdf-vm#bash#cli#elixir#elvish#erlang#fish#golang
RAW Doc

File: README.md

asdf

Manage multiple runtime versions with a single CLI tool, extendable via plugins - docs at asdf-vm.com

asdf is a CLI tool that can manage multiple language runtime versions on a per-project basis. It is like gvm, nvm, rbenv & pyenv (and more) all in one! Simply install your language's plugin!

Why use asdf?

  • single CLI for multiple languages
  • consistent commands to manage all your languages
  • single global config keeping defaults in one place
  • single .tool-versions config file per project
  • support for existing config files .node-version, .nvmrc, .ruby-version for easy migration
  • automatically switches runtime versions as you traverse your directories
  • simple plugin system to add support for your language of choice
  • shell completion available for common shells (Bash, Zsh, Fish, Elvish)

Documentation

Please head over to the documentation site for more information!

Contributing

See CONTRIBUTING.md in the repo or the Contributing section on the docs site.

Community & Questions

  • FAQ
  • GitHub Issues: report a bug or raise a feature request to the asdf core team
  • StackOverflow Tag: see existing Q&A for asdf. Some of the core team watch this tag in addition to our helpful community

Ballad of asdf

Once upon a time there was a programming language
There were many versions of it
So people wrote a version manager for it
To switch between versions for projects
Different, old, new.

Then there came more programming languages
So there came more version managers
And many commands for them

I installed a lot of them
I learnt a lot of commands

Then I said, just one more version manager
Which I will write instead

So, there came another version manager
asdf version manager - https://github.com/asdf-vm/asdf

A version manager so extendable
for which anyone can create a plugin
To support their favourite language
No more installing more version managers
Or learning more commands

This was the mail I wrote to a few friends to tell them about the project. Thanks to @roshanvid for suggesting that this go into the readme

[@HashNuke](https://github.com/HashNuke)

File: docs/contribute/core.md

asdf

asdf core contribution guide.

Initial Setup

Fork asdf on GitHub and/or Git clone the default branch:

shell
# clone your fork
git clone https://github.com/<GITHUB_USER>/asdf.git
# or clone asdf
git clone https://github.com/asdf-vm/asdf.git

The tools for core development are in this repo's .tool-versions. If you wish to manage with asdf itself, add the plugins:

shell
asdf plugin add bats https://github.com/timgluz/asdf-bats.git
asdf plugin add shellcheck https://github.com/luizm/asdf-shellcheck.git
asdf plugin add shfmt https://github.com/luizm/asdf-shfmt.git

Install the versions to develop asdf with:

shell
asdf install

It may be useful to not use asdf to manage the tools during development on your local machine as you may need to break functionality which would then break your dev tooling. Here's the raw list of tools:

  • bats-core: Bash Automated Testing System, for unit testing Bash or POSIX compliant scripts.
  • shellcheck: Static analysis tool for shell scripts.
  • shfmt: A shell parser, formatter, and interpreter with bash support; includes shfmt

Development

If you want to try out your changes without making change to your installed asdf, you can set the $ASDF_DIR variable to the path where you cloned the repository, and temporarily prepend the bin and shims directory of the directory to your path.

It is best to format, lint and test your code locally before you commit or push to the remote. Use the following scripts/commands:

shell
# Lint
./scripts/lint.bash --check

# Fix & Format
./scripts/lint.bash --fix

# Test: all tests
./scripts/test.bash

# Test: for specific command
bats test/list_commands.bash

::: tip

Add tests! - Tests are required for new features and speed up review of bug fixes. Please cover new code paths before you create a Pull Request. See bats-core documentation

:::

Gitignore

The following is the .gitignore file in the asdf-vm/asdf repository. We ignore project-specific files. Files specific to your OS, tools or workflows should be ignored in your global .gitignore configuration, see here for more details.

<<< @/../.gitignore

`.git-blame-ignore-revs`

asdf uses a .git-blame-ignore-revs to reduce noise when running a blame. See the git blame documentation for more information.

Use the file with git blame like so:

sh
git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats

Optionally, configure to use the file on every invocation of blame without manually supplying it:

sh
git config blame.ignoreRevsFile .git-blame-ignore-revs

It is possible to configure IDEs to use this file. For example, when using VSCode (with GitLens), write the following to .vscode/settings.json:

json
{
  "gitlens.advanced.blame.customArguments": [
    "--ignore-revs-file",
    ".git-blame-ignore-revs"
  ]
}

Bats Testing

Execute tests locally with:

shell
./scripts/test.bash

Before writing tests please read:

Bats Tips

Bats debugging can be difficult at times. Using the TAP output with -t flag will enable you to print outputs with the special file descriptor >&3 during test execution, simplifying debugging. As an example:

shell
# test/some_tests.bats

printf "%s\n" "Will not be printed during bats test/some_tests.bats"
printf "%s\n" "Will be printed during bats -t test/some_tests.bats" >&3

This is further documented in bats-core Printing to the Terminal.

Pull Requests, Releases & Conventional Commits

asdf is using an automated release tool called Release Please to automatically bump the SemVer version and generate the Changelog. This information is determined by reading the commit history since the last release.

Conventional Commit messages define the format of the Pull Request Title which becomes the commit message format on the default branch. This is enforced with GitHub Action amannn/action-semantic-pull-request.

Conventional Commit follows this format:

text
<type>[optional scope][optional !]: <description>


fix: some fix
feat: a new feature
docs: some documentation update
docs(website): some change for the website
feat!: feature with breaking change

The full list of <types> are: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.

  • !: indicates a breaking change
  • fix: will create a new SemVer patch
  • feat: will create a new SemVer minor
  • <type>!: will create a new SemVer major

The Pull Request Title must follow this format.

::: tip

Use Conventional Commit message format for your Pull Request Title.

:::

Docker Images

The asdf-alpine and asdf-ubuntu projects are an ongoing effort to provide Dockerized images of some asdf tools. You can use these docker images as base for your development servers, or for running your production apps.

File: docs/contribute/documentation.md

Docs & Site

Documentation & site contribution guide.

Initial Setup

Fork asdf on GitHub and/or Git clone the default branch:

shell
# clone your fork
git clone https://github.com/<GITHUB_USER>/asdf.git
# or clone asdf
git clone https://github.com/asdf-vm/asdf.git

The tools for Docs site development are managed with asdf in the docs/.tool-versions. Add the plugins with:

shell
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs

Install the tool version(s) with:

shell
asdf install
  • Node.js: JavaScript runtime built on Chrome's V8 JavaScript engine.

Install Node.js dependencies from docs/package.json:

shell
npm install

Development

VitePress (v2) is the Static Site Generator (SSG) we use to build the asdf documentation site. It was chosen to replace Docsify.js and subsequently VuePress as we would like to support an HTML only fallback when users do not have JavaScript available or enabled. This was not possible with Docsify & VitePress quickly supplanted VuePress. Other than this, the feature-set is largely the same, with the focus on writing Markdown files with minimal configuration.

package.json contains the scripts required for development:

@code json{3-5}

To start the local development server:

shell
npm run dev

Format the code before committing:

shell
npm run fmt

Pull Requests, Releases & Conventional Commits

asdf is using an automated release pipeline which relies on Conventional Commits in PR titles. Detailed documentation found in the core contribution guide.

When creating a PR for documentation changes please make the PR title with the Conventional Commit type docs in the format docs: <description>.

Vitepress

Configuration of the site is contained within a few TypeScript files with JS Objects used to represent the config. They are:

To simplify the root config, the larger JS Objects representing the navbar and sidebar configuration have been extracted and separated by their locale. See both in:

  • docs/.vitepress/navbars.js
  • docs/.vitepress/sidebars.js

With the official documentation for these configs living in the Default Theme Reference.

I18n

VitePress has first-class support for internationalization. The
root config docs/.vitepress/config.js defines the supported locales with their URL, title in the selection dropdown menu and navbar/sidebar configs references.

The navbar/sidebar configs are captured in the aforementioned config files, separated by locale and exported individually.

The markdown content for each locale must fall under a folder with the same name as the keys for locales in the root config. That is:

js
// docs/.vitepress/config.js
export default defineConfig({
  ...
  locales: {
    root: {
      label: "English",
        lang: "en-US",
        themeConfig: {
        nav: navbars.en,
          sidebar: sidebars.en,
      },
    },
    "pt-br": {
      label: "Brazilian Portuguese",
        lang: "pr-br",
        themeConfig: {
        nav: navbars.pt_br,
          sidebar: sidebars.pt_br,
      },
    },
    "zh-hans": {
      label: "็ฎ€ไฝ“ไธญๆ–‡",
        lang: "zh-hans",
        themeConfig: {
        nav: navbars.zh_hans,
          sidebar: sidebars.zh_hans,
      },
    },
  },
})

/pt-BR/ will require the same set of markdown files located under docs/pt-BR/, like so:

shell
docs
โ”œโ”€ README.md
โ”œโ”€ foo.md
โ”œโ”€ nested
โ”‚  โ””โ”€ README.md
โ””โ”€ pt-BR
   โ”œโ”€ README.md
   โ”œโ”€ foo.md
   โ””โ”€ nested
      โ””โ”€ README.md

The official VitePress i18n documentation goes into more detail.

File: docs/contribute/first-party-plugins.md

First-Party Plugins

The asdf core team has authored some plugins relevant to their daily work life. Help is always welcome in maintaining and improving these plugins. See the associated repo for each linked below:

For community plugins, see:

File: docs/contribute/github-actions.md

GitHub Actions

Thanks for your interest, please see the asdf actions repo for their existing Issues, conversations and Contributing Guidelines.

File: docs/guide/getting-started.md

Getting Started

1. Install asdf

asdf can be installed in several different ways:

::: details With Package Manager - Recommended

Package Manager Command
Homebrew brew install asdf
Zypper zypper install asdf
Pacman git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si or use your preferred AUR helper

:::

:::: details Download Pre-Compiled Binary - Easy

Install asdf

  1. Visit https://github.com/asdf-vm/asdf/releases and download the appropriate archive for your operating system/architecture combination.
  2. Extract the asdf binary in the archive into a directory on your $PATH.
  3. Verify asdf is on your shell's $PATH by running type -a asdf. The directory you placed the asdf binary in should be listed on the first line of the output from type. If it is not that means step #2 was not completed correctly.

::::

:::: details With go install

Install asdf

  1. Install Go
  2. Run go install github.com/asdf-vm/asdf/cmd/[email protected]

::::

:::: details Build from Source

Install asdf

  1. Clone the asdf repository:
shell
git clone https://github.com/asdf-vm/asdf.git --branch v0.20.0
  1. Run make
  2. Copy the asdf binary into a directory on your $PATH.
  3. Verify asdf is on your shell's $PATH by running type -a asdf. The directory you placed the asdf binary in should be listed on the first line of the output from type. If it is not that means step #3 was not completed correctly.

::::

2. Configure asdf

::: tip Note
Most users DO NOT need to customize the location that asdf writes plugin,
install, and shim data to. However, if $HOME/.asdf isn't the directory you
want asdf writing to, you can change it. Specify the directory by exporting
a variable named ASDF_DATA_DIR in your shell's RC file.
:::

There are many different combinations of Shells, OSs & Installation methods all of which affect the configuration here. Expand the selection below that best matches your system.

::: details Bash

macOS Catalina or newer: The default shell has changed to ZSH. Unless changing back to Bash, follow the ZSH instructions.

Pacman: bash-completion needs to be installed for the completions to work.

Add shims directory to path (required)

Add the following to ~/.bash_profile:

shell
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

Custom data directory (optional)

Add the following to ~/.bash_profile above the line you added above:

shell
export ASDF_DATA_DIR="/your/custom/data/dir"

Set up shell completions (optional)

Completions must be configured by adding the following to your .bashrc:

shell
. <(asdf completion bash)

:::

::: details Fish

Add shims directory to path (required)

Add the following to ~/.config/fish/config.fish:

shell
# ASDF configuration code
if test -z $ASDF_DATA_DIR
    set _asdf_shims "$HOME/.asdf/shims"
else
    set _asdf_shims "$ASDF_DATA_DIR/shims"
end

# Do not use fish_add_path (added in Fish 3.2) because it
# potentially changes the order of items in PATH
if not contains $_asdf_shims $PATH
    set -gx --prepend PATH $_asdf_shims
end
set --erase _asdf_shims

Custom data directory (optional)

Pacman: Completions are automatically configured on installation by the AUR package.

Add the following to ~/.config/fish/config.fish above the lines you added above:

shell
set -gx --prepend ASDF_DATA_DIR "/your/custom/data/dir"

Set up shell completions (optional)

Completions must be configured manually with the following command:

shell
$ asdf completion fish > ~/.config/fish/completions/asdf.fish

:::

::: details Elvish

Add shims directory to path (required)

Add the following to ~/.config/elvish/rc.elv:

shell
var asdf_data_dir = ~'/.asdf'
if (and (has-env ASDF_DATA_DIR) (!=s $E:ASDF_DATA_DIR '')) {
  set asdf_data_dir = $E:ASDF_DATA_DIR
}

if (not (has-value $paths $asdf_data_dir'/shims')) {
  set paths = [$path $@paths]
}

Custom data directory (optional)

Change the following line in the above snippet to set a custom data directory:

diff
-var asdf_data_dir = ~'/.asdf'
+var asdf_data_dir = '/your/custom/data/dir'

Set up shell completions (optional)

shell
$ asdf completion elvish >> ~/.config/elvish/rc.elv
$ echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

:::

::: details ZSH

Pacman: Completions are placed in a ZSH friendly location, but ZSH must be configured to use the autocompletions.

Add shims directory to path (required)

Add the following to ~/.zshrc:

shell
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

Custom data directory (optional)

Add the following to ~/.zshrc above the line you added above:

shell
export ASDF_DATA_DIR="/your/custom/data/dir"

Set up shell completions (optional)

Completions are configured by either a ZSH Framework asdf plugin (like asdf for oh-my-zsh) or by doing the following:

shell
$ mkdir -p "${ASDF_DATA_DIR:-$HOME/.asdf}/completions"
$ asdf completion zsh > "${ASDF_DATA_DIR:-$HOME/.asdf}/completions/_asdf"

Then add the following to your .zshrc:

shell
# append completions to fpath
fpath=(${ASDF_DATA_DIR:-$HOME/.asdf}/completions $fpath)
# initialise completions with ZSH's compinit
autoload -Uz compinit && compinit

Note

If you are using a custom compinit setup with a ZSH Framework, ensure compinit is below your sourcing of the framework

Completions are configured by either a ZSH Framework asdf or will need to be configured as per Homebrew's instructions. If you are using a ZSH Framework the associated plugin for asdf may need to be updated to use the new ZSH completions properly via fpath.
:::

::: details PowerShell Core

Add shims directory to path (required)

Add the following to ~/.config/powershell/profile.ps1:

shell
# Determine the location of the shims directory
if ($null -eq $ASDF_DATA_DIR -or $ASDF_DATA_DIR -eq '') {
  $_asdf_shims = "${env:HOME}/.asdf/shims"
}
else {
  $_asdf_shims = "$ASDF_DATA_DIR/shims"
}

# Then add it to path
$env:PATH = "${_asdf_shims}:${env:PATH}"

Custom data directory (optional)

Add the following to ~/.config/powershell/profile.ps1 above the snippet you added above:

shell
$env:ASDF_DATA_DIR = "/your/custom/data/dir"

Shell completions not available for PowerShell

:::

::: details Nushell

Add shims directory to path (required)

Add the following to ~/.config/nushell/config.nu:

shell
const asdf_data_dir = '~/.asdf' | path expand # or wherever you like
const asdf_shims = [$asdf_data_dir shims] | path join
$env.PATH = $env.PATH | where {$in != $asdf_shims} | prepend $asdf_shims

Custom data directory (required when $asdf_data_dir != '~/.asdf')

If you set $asdf_data_dir to something different than the default ~/.asdf then you must add the following to ~/.config/nushell/config.nu:

shell
$env.ASDF_DATA_DIR = $asdf_data_dir

Set up shell completions (optional)

Add the following to ~/.config/nushell/config.nu, after the required setup:

shell
const asdf_cmp = [$asdf_data_dir completions nushell.nu] | path join
mkdir ($asdf_cmp | path dirname)
asdf completion nushell | save -f $asdf_cmp
source $asdf_cmp

:::

::: details POSIX Shell

Add shims directory to path (required)

Add the following to ~/.profile:

shell
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

Custom data directory (optional)

Add the following to ~/.profile above the line you added above:

shell
export ASDF_DATA_DIR="/your/custom/data/dir"

:::

asdf scripts need to be sourced after you have set your $PATH and after you have sourced your framework (oh-my-zsh etc).

Restart your shell so that PATH changes take effect. Opening a new terminal tab will usually do it.

Core Installation Complete!

This completes the installation of the asdf core :tada:

asdf is only useful once you install a plugin, install a tool and manage its versions. Continue the guide below to learn how to do this.

4. Install a Plugin

For demonstration purposes we will install & set Node.js via the asdf-nodejs plugin.

Plugin Dependencies

Each plugin has dependencies so we need to check the plugin repo where they should be listed. For asdf-nodejs they are:

OS Dependency Installation
Debian apt-get install dirmngr gpg curl gawk
CentOS/ Rocky Linux/ AlmaLinux yum install gnupg2 curl gawk
macOS brew install gpg gawk

We should install dependencies first as some Plugins have post-install hooks.

Install the Plugin

shell
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

5. Install a Version

Now we have a plugin for Node.js we can install a version of the tool.

We can see which versions are available with asdf list all nodejs or a subset of versions with asdf list all nodejs 14.

We will just install the latest available version:

shell
asdf install nodejs latest

::: tip Note
asdf enforces exact versions. latest is a helper throughout asdf that will resolve to the actual version number at the time of execution.
:::

6. Set a Version

asdf performs a version lookup of a tool in all .tool-versions files from the current working directory up to the $HOME directory. The lookup occurs just-in-time when you execute a tool that asdf manages.

::: warning
Without a version listed for a tool execution of the tool will error. asdf current will show you the tool & version resolution, or absence of, from your current directory so you can observe which tools will fail to execute.
:::

Because asdf looks for a .tool-versions file in the current directory first, and if the file is not found it then climbs up the file tree looking for a .tool-versions in a parent directory until it finds one. If no .tool-versions file is found the version resolution process will fail and an error will be printed.

If you want to set a default version that will apply to all directories you work in you can set a version in $HOME/.tool-versions. Any directory under your home directory will have that same version set, unless a particular directory sets another version.

shell
asdf set -u nodejs 16.5.0

$HOME/.tool-versions will then look like:

text
nodejs 16.5.0

Some OSs already have tools installed that are managed by the system and not asdf, python is a common example. You need to tell asdf to pass the management back to the system. The Versions reference section will guide you.

The first place asdf looks for a version is your current working directory ($PWD/.tool-versions). This may be a directory containing a source code or Git repository for a project. When in your desired directory execute you can use asdf set to set the version:

shell
asdf set nodejs 16.5.0

$PWD/.tool-versions will then look like:

text
nodejs 16.5.0

Using Existing Tool Version Files

asdf supports the migration from existing version files from other version managers. Eg: .ruby-version for the case of rbenv. This is supported on a per-plugin basis.

asdf-nodejs supports this via both .nvmrc and .node-version files. To enable this, add the following to your asdf configuration file $HOME/.asdfrc:

text
legacy_version_file = yes

See the configuration reference page for more config options.

Guide Complete!

That completes the Getting Started guide for asdf :tada: You can now manage nodejs versions for your project. Follow similar steps for each type of tool in your project!

asdf has many more commands to become familiar with, you can see them all by running asdf --help or asdf. The core of the commands are broken into three categories:

File: docs/guide/getting-started-legacy.md

Getting Started

asdf installation involves:

  1. Installing dependencies
  2. Downloading asdf core
  3. Installing asdf
  4. Installing a plugin for each tool/runtime you wish to manage
  5. Installing a version of the tool/runtime
  6. Setting global and project versions via .tool-versions config files

1. Install Dependencies

asdf primarily requires git & curl. Here is a non-exhaustive list of commands to run for your package manager (some might automatically install these tools in later steps).

OS Package Manager Command
linux Aptitude apt install curl git
linux DNF dnf install curl git
linux Pacman pacman -S curl git
linux Zypper zypper install curl git
macOS Homebrew brew install coreutils curl git
macOS Spack spack install coreutils curl git

::: tip Note

sudo may be required depending on your system configuration.

:::

2. Download asdf

Official Download

shell
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.15.0

Community Supported Download Methods

We highly recommend using the official git method.

Method Command
Homebrew brew install asdf
Pacman git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si or use your preferred AUR helper

3. Install asdf

There are many different combinations of Shells, OSs & Installation methods all of which affect the configuration here. Expand the selection below that best matches your system.

macOS users, be sure to read the warning about path_helper at the end of this section.

::: details Bash & Git

Add the following to ~/.bashrc:

shell
. "$HOME/.asdf/asdf.sh"

Completions must be configured by adding the following to your .bashrc:

shell
. "$HOME/.asdf/completions/asdf.bash"

:::

::: details Bash & Git (macOS)

If using macOS Catalina or newer, the default shell has changed to ZSH. Unless changing back to Bash, follow the ZSH instructions.

Add the following to ~/.bash_profile:

shell
. "$HOME/.asdf/asdf.sh"

Completions must be configured manually with the following entry in your .bash_profile:

shell
. "$HOME/.asdf/completions/asdf.bash"

:::

::: details Bash & Homebrew

Add asdf.sh to your ~/.bashrc with:

shell
echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bashrc

Completions will need to be configured as per Homebrew's instructions or with the following:

shell
echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bashrc

:::

::: details Bash & Homebrew (macOS)

If using macOS Catalina or newer, the default shell has changed to ZSH. Unless changing back to Bash, follow the ZSH instructions.

Add asdf.sh to your ~/.bash_profile with:

shell
echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bash_profile

Completions will need to be configured as per Homebrew's instructions or with the following:

shell
echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bash_profile

:::

::: details Bash & Pacman

Add the following to ~/.bashrc:

shell
. /opt/asdf-vm/asdf.sh

bash-completion needs to be installed for the completions to work.
:::

::: details Fish & Git

Add the following to ~/.config/fish/config.fish:

shell
source ~/.asdf/asdf.fish

Completions must be configured manually with the following command:

shell
mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions

:::

::: details Fish & Homebrew

Add asdf.fish to your ~/.config/fish/config.fish with:

shell
echo -e "\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fish

Completions are handled by Homebrew for the Fish shell. Friendly!
:::

::: details Fish & Pacman

Add the following to ~/.config/fish/config.fish:

shell
source /opt/asdf-vm/asdf.fish

Completions are automatically configured on installation by the AUR package.
:::

::: details Elvish & Git

Add asdf.elv to your ~/.config/elvish/rc.elv with:

shell
mkdir -p ~/.config/elvish/lib; ln -s ~/.asdf/asdf.elv ~/.config/elvish/lib/asdf.elv
echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv
echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

Completions are automatically configured.

:::

::: details Elvish & Homebrew

Add asdf.elv to your ~/.config/elvish/rc.elv with:

shell
mkdir -p ~/.config/elvish/lib; ln -s (brew --prefix asdf)/libexec/asdf.elv ~/.config/elvish/lib/asdf.elv
echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv
echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

Completions are automatically configured.
:::

::: details Elvish & Pacman

Add asdf.elv to your ~/.config/elvish/rc.elv with:

shell
mkdir -p ~/.config/elvish/lib; ln -s /opt/asdf-vm/asdf.elv ~/.config/elvish/lib/asdf.elv
echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv
echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv

Completions are automatically configured.
:::

::: details ZSH & Git

Add the following to ~/.zshrc:

shell
. "$HOME/.asdf/asdf.sh"

OR use a ZSH Framework plugin like asdf for oh-my-zsh which will source this script and setup completions.

Completions are configured by either a ZSH Framework asdf plugin or by adding the following to your .zshrc:

shell
# append completions to fpath
fpath=(${ASDF_DIR}/completions $fpath)
# initialise completions with ZSH's compinit
autoload -Uz compinit && compinit
  • if you are using a custom compinit setup, ensure compinit is below your sourcing of asdf.sh
  • if you are using a custom compinit setup with a ZSH Framework, ensure compinit is below your sourcing of the framework

:::

::: details ZSH & Homebrew

Add asdf.sh to your ~/.zshrc with:

shell
echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc

OR use a ZSH Framework plugin like asdf for oh-my-zsh which will source this script and setup completions.

Completions are configured by either a ZSH Framework asdf or will need to be configured as per Homebrew's instructions. If you are using a ZSH Framework the associated plugin for asdf may need to be updated to use the new ZSH completions properly via fpath.
:::

::: details ZSH & Pacman

Add the following to ~/.zshrc:

shell
. /opt/asdf-vm/asdf.sh

Completions are placed in a ZSH friendly location, but ZSH must be configured to use the autocompletions.
:::

::: details PowerShell Core & Git

Add the following to ~/.config/powershell/profile.ps1:

shell
. "$HOME/.asdf/asdf.ps1"

:::

::: details PowerShell Core & Homebrew

Add asdf.sh to your ~/.config/powershell/profile.ps1 with:

shell
echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.ps1\"" >> ~/.config/powershell/profile.ps1

:::

::: details PowerShell Core & Pacman

Add the following to ~/.config/powershell/profile.ps1:

shell
. /opt/asdf-vm/asdf.ps1

:::

::: details Nushell & Git

Add asdf.nu to your ~/.config/nushell/config.nu with:

shell
"\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path

Completions are automatically configured
:::

::: details Nushell & Homebrew

Add asdf.nu to your ~/.config/nushell/config.nu with:

shell
"\n$env.ASDF_DIR = (brew --prefix asdf | str trim | into string | path join 'libexec')\n source " +  (brew --prefix asdf | str trim | into string | path join 'libexec/asdf.nu') | save --append $nu.config-path

Completions are automatically configured
:::

::: details Nushell & Pacman

Add asdf.nu to your ~/.config/nushell/config.nu with:

shell
"\n$env.ASDF_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path

Completions are automatically configured.
:::

::: details POSIX Shell & Git

Add the following to ~/.profile:

shell
export ASDF_DIR="$HOME/.asdf"
. "$HOME/.asdf/asdf.sh"

:::

::: details POSIX Shell & Homebrew

Add asdf.sh to your ~/.profile with:

shell
echo -e "\nexport ASDF_DIR=\"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile
echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile

:::

::: details POSIX Shell & Pacman

Add the following to ~/.profile:

shell
export ASDF_DIR="/opt/asdf-vm"
. /opt/asdf-vm/asdf.sh

:::

asdf scripts need to be sourced after you have set your $PATH and after you have sourced your framework (oh-my-zsh etc).

::: warning
On macOS, starting a Bash or Zsh shell automatically calls a utility called path_helper. path_helper can rearrange items in PATH (and MANPATH), causing inconsistent behavior for tools that require specific ordering. To workaround this, asdf on macOS defaults to forcibly adding its PATH-entries to the front (taking highest priority). This is controllable with the ASDF_FORCE_PREPEND variable.
:::

Restart your shell so that PATH changes take effect. Opening a new terminal tab will usually do it.

Core Installation Complete!

This completes the installation of the asdf core :tada:

asdf is only useful once you install a plugin, install a tool and manage its versions. Continue the guide below to learn how to do this.

4. Install a Plugin

For demonstration purposes we will install & set Node.js via the asdf-nodejs plugin.

Plugin Dependencies

Each plugin has dependencies so we need to check the plugin repo where they should be listed. For asdf-nodejs they are:

OS Dependency Installation
Debian apt-get install dirmngr gpg curl gawk
CentOS/ Rocky Linux/ AlmaLinux yum install gnupg2 curl gawk
macOS brew install gpg gawk

We should install dependencies first as some Plugins have post-install hooks.

Install the Plugin

shell
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

5. Install a Version

Now we have a plugin for Node.js we can install a version of the tool.

We can see which versions are available with asdf list all nodejs or a subset of versions with asdf list all nodejs 14.

We will just install the latest available version:

shell
asdf install nodejs latest

::: tip Note
asdf enforces exact versions. latest is a helper throughout asdf that will resolve to the actual version number at the time of execution.
:::

6. Set a Version

asdf performs a version lookup of a tool in all .tool-versions files from the current working directory up to the $HOME directory. The lookup occurs just-in-time when you execute a tool that asdf manages.

::: warning
Without a version listed for a tool execution of the tool will error. asdf current will show you the tool & version resolution, or absence of, from your current directory so you can observe which tools will fail to execute.
:::

Global

Global defaults are managed in $HOME/.tool-versions. Set a global version with:

shell
asdf global nodejs latest

$HOME/.tool-versions will then look like:

text
nodejs 16.5.0

Some OSs already have tools installed that are managed by the system and not asdf, python is a common example. You need to tell asdf to pass the management back to the system. The Versions reference section will guide you.

Local

Local versions are defined in the $PWD/.tool-versions file (your current working directory). Usually, this will be the Git repository for a project. When in your desired directory execute:

shell
asdf local nodejs latest

$PWD/.tool-versions will then look like:

text
nodejs 16.5.0

Using Existing Tool Version Files

asdf supports the migration from existing version files from other version managers. Eg: .ruby-version for the case of rbenv. This is supported on a per-plugin basis.

asdf-nodejs supports this via both .nvmrc and .node-version files. To enable this, add the following to your asdf configuration file $HOME/.asdfrc:

text
legacy_version_file = yes

See the configuration reference page for more config options.

Guide Complete!

That completes the Getting Started guide for asdf :tada: You can now manage nodejs versions for your project. Follow similar steps for each type of tool in your project!

asdf has many more commands to become familiar with, you can see them all by running asdf --help or asdf. The core of the commands are broken into three categories:

File: docs/guide/introduction.md

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 shims 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 nvm, n and rbenv 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-direnv to integrate direnv behaviour with asdf.

See direnv docs 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 docs 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 docs 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.

::: tip 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.
:::

File: docs/guide/upgrading-to-v0-16.md

Upgrading to 0.16.0

asdf versions 0.15.0 and older were written in Bash and distributed as a set of
Bash scripts with the asdf function loaded into your shell. asdf version
0.16.0 is a complete rewrite of asdf in Go. Since it is a complete rewrite
there are a number of breaking changes and it is now
a binary rather than a set of scripts.

Installation

Installation of version 0.16.0 and newer is much simpler than previous versions
of asdf. It's just three steps:

  • Download the appropriate asdf binary for your operating system/architecture
    combo via any of the install methods available.
    If using a package manager verify it's installing version 0.16.0 or later.
  • Add $ASDF_DATA_DIR/shims to the front of your $PATH.
  • Optionally, if you previously had a customized location for asdf data, set
    ASDF_DATA_DIR to the directory you already had the old version installing
    plugins, versions, and shims.

If your operating system's package manager already offers asdf 0.16.0 that is
probably the best method for installing it. Upgrading asdf is now only possible
via OS package managers and manual installation. There is no self-upgrade
feature.

Upgrading Without Losing Data

You can upgrade to the latest version of asdf without losing your existing
install data. It's the same sequence of steps as above.

1. Download the appropriate `asdf` binary for your operating system & architecture

Download the binary from the GitHub releases page and place it in a directory on your path. I chose to place
the asdf binary in $HOME/bin and then added $HOME/bin to the front of my
$PATH:

text
# In .zshrc, .bashrc, etc...
export PATH="$HOME/bin:$PATH"

2. Set `ASDF_DATA_DIR`

Run asdf info and copy the line containing the ASDF_DATA_DIR variable:

text
...
ASDF_DATA_DIR="/home/myuser/.asdf"
...

In your shell RC file (.zshrc if Zsh, .bashrc if Bash, etc...) add a line
to the end setting ASDF_DATA_DIR to that same value:

bash
export ASDF_DATA_DIR="/home/myuser/.asdf"

3. Add `$ASDF_DATA_DIR/shims` to the front of your `$PATH`

In your shell RC file (same file as step #2) add $ASDF_DATA_DIR/shims to the
front of your path:

bash
export ASDF_DATA_DIR="/home/myuser/.asdf"
export PATH="$ASDF_DATA_DIR/shims:$PATH"

4. Remove Old Config

In your shells RC file you'll have the old code running the asdf shell script at
startup. It'll probably look something like this:

text
. "$HOME/.asdf/asdf.sh"

Or this:

text
. /opt/homebrew/opt/asdf/libexec/asdf.sh

Comment out these lines or remove them entirely.

If you are not using Zsh or Bash please see the legacy
Getting Started guide
for the code snippet you need to remove.

5. Regenerate Shims

Verify that asdf command in your shell session is version 0.16.0+ by running
asdf --help. If you still see an older version you will need to start a new
shell session.

Once you've verified the asdf command is the new version run asdf reshim to
regenerate all shims. This is necessary as the old shims may still reference
the old Bash version.

Testing

If you aren't sure if the upgrade to 0.16.0 will break things for you can you
can test by installing 0.16.0 in addition to your existing version as described
above in "Upgrading Without Losing Data". If it turns out that the upgrade to
0.16.0 or greater breaks things for you you can revert back to the older
version. Remove the lines you added to your shell RC file, and add back in the
lines you removed or commented out.

Removing old files

Only do this after you've completed all the steps above and have verified
your new asdf installation is working correctly! After upgrade there are
various files you can remove from the old Bash-script based versions of asdf.
Most of the files in your data directory (typically ~/.asdf/) can be removed.
Note that you don't have to do this. There is no harm in keeping the files from
old versions of asdf around. The only directories that must be kept are:

  • downloads/
  • installs/
  • plugins/
  • shims/

The rest can be deleted. This can be done in one command with find:

text
find ${ASDF_DATA_DIR:-$HOME/.asdf}/ -maxdepth 1 -mindepth 1 -not -name downloads -not -name plugins -not -name installs -not -name shims -exec rm -r {} \;

Breaking Changes

Hyphenated commands have been removed

asdf version 0.15.0 and earlier supported by hyphenated and non-hyphenated
versions of certain commands. With version 0.16.0 only the non-hyphenated
versions are supported. The affected commands:

  • asdf list-all -> asdf list all
  • asdf plugin-add -> asdf plugin add
  • asdf plugin-list -> asdf plugin list
  • asdf plugin-list-all -> asdf plugin list all
  • asdf plugin-update -> asdf plugin update
  • asdf plugin-remove -> asdf plugin remove
  • asdf plugin-test -> asdf plugin test
  • asdf shim-versions -> asdf shimversions

`asdf global` and `asdf local` commands have been replaced with `asdf set`

asdf global and asdf local have been removed. The "global" and "local"
terminology was wrong and also misleading. asdf doesn't actually support
"global" versions that apply everywhere. Any version that was specified with
asdf global could easily be overridden by a .tool-versions file in your
current directory specifying a different version. This was confusing to users.
The new asdf set behaves the same as asdf local by default, but also has
flags for setting versions in the user's home directory (--home) and in an
existing .tool-versions file in one of the parent directories (--parent).
This new interface will hopefully convey a better understanding of how asdf
resolves versions and provide equivalent functionality.

`asdf update` command has been removed

Updates can no longer be performed this way. Use your OS package manager or
download the latest binary manually. Additionally, the asdf update command
present in versions 0.15.0 and older cannot upgrade to version 0.16.0 because
the install process has changed. You cannot upgrade to the latest Go
implementation using asdf update.

`asdf shell` command has been removed

This command actually set an environment variable in the user's current shell
session. It was able to do this because asdf was actually a shell function,
not an executable. The new rewrite removes all shell code from asdf, and it is
now a binary rather than a shell function, so setting environment variables
directly in the shell is no longer possible.

`asdf current` has changed

Instead of three columns in the output, with the last being either the location
the version is set or a suggested command that could be run to set or install a
version. The third column has been split into two columns. The third column now
only indicates the source of the version if it is set (typically either version
file or environment variable) and the fourth is a boolean indicating whether
the specified version is actually installed. If it is not installed, a
suggested install command is shown.

Plugin extension commands must now be prefixed with `cmd`

Previously plugin extension commands could be run like this:

text
asdf nodejs nodebuild --version

Now they must be prefixed with cmd to avoid causing confusion with built-in
commands:

text
asdf cmd nodejs nodebuild --version

Extension commands have been redesigned

There are a number of breaking changes for plugin extension commands:

  • They must be runnable by exec syscall. If your extension commands are shell
    scripts in order to be run with exec they must start with a proper shebang
    line.
  • They can now be binaries or scripts in any language. It no
    longer makes sense to require a .bash extension as it is misleading.
  • They must have executable permission set.
  • They are no longer sourced by asdf as Bash scripts when they lack executable
    permission.

Additionally, only the first argument after plugin name is used to determine
the extension command to run. This means effectively there is the default
command extension command that asdf defaults to when no command matching the
first argument after plugin name is found. For example:

text
foo/
  lib/commands/
    command
    command-bar
    command-bat-man

Previously these scripts would work like this:

text
$ asdf cmd foo         # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command`
$ asdf cmd foo bar     # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bar`
$ asdf cmd foo bat man # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat-man`

Now:

text
$ asdf cmd foo         # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command`
$ asdf cmd foo bar     # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bar`
$ asdf cmd foo bat man # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat man`

Executables Shims Resolve to Must Runnable by `syscall.Exec`

The most obvious example of this breaking change are scripts that lack a proper
shebang line. asdf 0.15.0 and older were implemented in Bash, so as long it was
an executable that could be executed with Bash it would run. This mean that
scripts lacking a shebang could still be run by asdf exec. With asdf 0.16.x
implemented in Go we now invoke executables via Go's syscall.Exec function,
which cannot handle scripts lacking a shebang.

In practice this isn't much of a problem. Most shell scripts DO contain a
shebang line. If a tool managed by asdf provides scripts that don't have a
shebang line one will need to be added to them.

Custom shim templates are no longer supported

This was a rarely used feature. The only plugin maintained by the core team
that used it was the Elixir plugin, and it no longer needs it. This feature
was originally added so that shim that get evaluated by a program rather than
executed contain code that is suitable for evaluation by a particular program
(in the case of Elixir this was the iex shell). Upon further investigation
it seems this feature only exists because the PATH for executables was
sometimes improperly set to include the shims rather than the other
executables for the selected version(s).

File: docs/ja-jp/guide/parts/install-dependencies.md

ไพๅญ˜้–ขไฟ‚ใฎใ‚คใƒณใ‚นใƒˆใƒผใƒซ

asdfใฎๅ‹•ไฝœใซใฏgitใŒๅฟ…่ฆใงใ™ใ€‚ไปฅไธ‹ใฎ่กจใฏใ€ ใ‚ใชใŸใŒไฝฟ็”จใ—ใฆใ„ใ‚‹ ใƒ‘ใƒƒใ‚ฑใƒผใ‚ธใƒžใƒใƒผใ‚ธใƒฃใงๅฎŸ่กŒใ™ใ‚‹ใ‚ณใƒžใƒณใƒ‰ใฎ ไธ€้ƒจไพ‹ ใงใ™(ใ„ใใคใ‹ใฎใƒ„ใƒผใƒซใฏใ€ๅพŒใฎๆ‰‹้ †ใง่‡ชๅ‹•็š„ใซใ‚คใƒณใ‚นใƒˆใƒผใƒซใ•ใ‚Œใพใ™)ใ€‚

OS ใƒ‘ใƒƒใ‚ฑใƒผใ‚ธใƒžใƒใƒผใ‚ธใƒฃใƒผ ใ‚ณใƒžใƒณใƒ‰
linux Aptitude apt install git
linux DNF dnf install git
linux Pacman pacman -S git
linux Zypper zypper install git
macOS Homebrew brew install coreutils git
macOS Spack spack install coreutils git

::: tip ๅ‚™่€ƒ

ใŠไฝฟใ„ใฎใ‚ทใ‚นใƒ†ใƒ ใฎๆง‹ๆˆใซใ‚ˆใฃใฆใฏใ€sudoใŒๅฟ…่ฆใจใชใ‚‹ๅ ดๅˆใŒใ‚ใ‚Šใพใ™ใ€‚

:::

Explore Related Technologies & Topics

View All 9,111+ Repositories โ†’

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#asdf-vm Browse asdf-vm catalog โ†’ #bash Browse bash catalog โ†’ #cli Browse cli catalog โ†’ #elixir Browse elixir catalog โ†’ #elvish Browse elvish catalog โ†’ #erlang Browse erlang catalog โ†’ โšก MCP Servers Model Context Protocol โ†’ ๐Ÿง  Agent Skills Prompt & rule files โ†’ ๐Ÿ”Œ OpenAPI Specs REST & Swagger schemas โ†’