asdf - Elixir Version Manager

Open Issues
Last Commit
14 May 16
From Github Readme


extendable version manager

Supported languages include Ruby, Node.js, Elixir and more. Supporting a new language is as simple as this plugin API.


Copy-paste the following into command line:

git clone ~/.asdf

Depending on your OS, run the following

# For Ubuntu or other linux distros
echo '. $HOME/.asdf/' >> ~/.bashrc
echo '. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc

# OR for Max OSX
echo '. $HOME/.asdf/' >> ~/.bash_profile
echo '. $HOME/.asdf/completions/asdf.bash' >> ~/.bash_profile

If you use zsh or any other shell, replace .bashrc with the config file for the respective shell.

For fish, you can use the following:

echo 'source ~/.asdf/' >> ~/.config/fish/
mkdir -p ~/.config/fish/completions; and cp ~/.asdf/completions/ ~/.config/fish/completions

For most plugins, it is good if you have installed the following packages OR their equivalent on you OS

  • OS X: Install these via homebrew automake autoconf openssl libyaml readline libxslt libtool unixodbc
  • Ubuntu: automake autoconf libreadline-dev libncurses-dev libssl-dev libyaml-dev libxslt-dev libffi-dev libtool unixodbc-dev

That’s all ~! You are ready to use asdf


Manage plugins

Plugins are how asdf understands how to handle different packages. Below is a list of plugins for languages. There is a super-simple API for supporting more languages.

Add a plugin
asdf plugin-add <name> <git-url>
# asdf plugin-add erlang
List installed plugins
asdf plugin-list
# asdf plugin-list
Remove a plugin
asdf plugin-remove <name>
# asdf plugin-remove erlang
Update plugins
asdf plugin-update --all

If you want to update a specific package, just say so.

asdf plugin-update <name>
# asdf plugin-update erlang

Manage versions

asdf install <name> <version>
# asdf install erlang 17.3

asdf which <name>
# asdf which erlang
# 17.3

asdf uninstall <name> <version>
# asdf uninstall erlang 17.3

If a plugin supports downloading & compiling from source, you can also do this ref:foo (replace foo with the branch/tag/commit). You’ll have to use the same name when uninstalling too.

Lists installed versions
asdf list <name>
# asdf list erlang
List all available versions
asdf list-all <name>
# asdf list-all erlang

View current version

asdf local [name]
asdf global [name]
# asdf local
# asdf global
# asdf local elixir
# asdf global elixir

global reads from $HOME/.tool-versions.

local reads from $PWD/.tool-versions if it exists, or searches recursively in the parent directories until it finds a .tool-versions file.

Set current version

asdf global <name> <version>
asdf local <name> <version>
asdf global elixir 1.2.4

global writes the version to $HOME/.tool-versions.

local writes the version to $PWD/.tool-versions, creating it if needed.

The .tool-versions file

Add a .tool-versions file to your project dir and versions of those tools will be used. Global defaults can be set in the file $HOME/.tool-versions

This is what a .tool-versions file looks like:

ruby 2.2.0
nodejs 0.12.3

The versions can be in the following format:

  • 0.12.3 - an actual version. Plugins that support downloading binaries, will download binaries.
  • ref:v1.0.2-a or ref:39cb398vb39 - tag/commit/branch to download from github and compile
  • path:/src/elixir - a path to custom compiled version of a tool to use. For use by language developers and such.

To install all the tools defined in a .tool-versions file run the asdf install command with no other arguments in the directory containing the .tool-versions file.

You can view/modify the file by hand or use asdf local and asdf global to manage it.


Me (@HashNuke), High-fever, cold, cough.

Copyright 2014 to the end of time (MIT License)


Read the ballad.