ASDF, the version manager for all your languages

Why use ASDF?

ASDF is a version manager for programming languages. It's somewhat like RVM is for Ruby or NVM is for Node but it also supports Erlang, Elixir, Haskel, Ocaml, PHP, Python, Rust and many other languages.

Prereqs

This guide assumes you have homebrew and Xcode command line tools and nothing else. To see the setup of those from a fresh macOS Mojave install, see this short video. This document is much more up to date and includes notes added for various OS versions over the years.

Install dependencies (mac)

1. Install Postgres: brew install postgresql
2. Configure PostgreSQL to start on reboot: brew services start postgresql
3. Install other dependencies:

   brew install \
   coreutils automake autoconf openssl \
   libyaml readline libxslt libtool unixodbc \
   unzip curl gpg wxmac

Install dependencies (ubuntu)

1. Install PostgreSQL from Ubuntu's packages unless you have a reason to use a different distribution:

sudo apt install postgresql postgresql-client

2. Install the build tools and libraries needed for Erlang:

Ubuntu 24.04:

sudo apt install \
  build-essential autoconf m4 libncurses-dev libwxgtk3.2-dev \
  libwxgtk-webview3.2-dev libgl1-mesa-dev libglu1-mesa-dev \
  libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils \
  libssl-dev openjdk-21-jdk

Ubuntu 22.04:

sudo apt install \
  build-essential autoconf m4 libncurses-dev libwxgtk3.0-gtk3-dev \
  libwxgtk-webview3.0-gtk3-dev libgl1-mesa-dev libglu1-mesa-dev \
  libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils \
  libssl-dev openjdk-11-jdk

If you're setting up a headless server and do not need Observer or other wx tools, you can skip the libwxgtk*, libgl*, and Java packages and build Erlang with --without-wx --without-javac.

Older Ubuntu notes used libncurses5-dev; newer Ubuntu versions provide libncurses-dev instead.

Ubuntu 18.04:

sudo apt-get -y install \
build-essential autoconf m4 libncurses5-dev libwxgtk3.0-gtk3-dev \
libwxgtk-webview3.0-gtk3-dev libgl1-mesa-dev libglu1-mesa-dev \
libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils \
libncurses-dev openjdk-11-jdk

Install ASDF

ASDF 0.16+ is a Go rewrite and installs as a standalone asdf binary. Check the current install instructions on the ASDF site or GitHub repo: https://github.com/asdf-vm/asdf

After installing the binary, make sure ASDF's shims are on your PATH. For Bash, that usually means adding this to ~/.bashrc:

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

Restart your shell and run:

asdf version

Legacy Bash ASDF

Older servers may still use the pre-0.16 Bash implementation of ASDF. For those servers, the install looked like this:

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

Then add it to your shell:

echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.bashrc
echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc

If the completions file is missing, guard that line instead:

[ -f "$HOME/.asdf/completions/asdf.bash" ] && . "$HOME/.asdf/completions/asdf.bash"

Restart your shell and run asdf version to verify that it's installed.

Basic commands

• asdf plugin-list-all: shows all the plugins (i.e., languages) available
• asdf plugin-add <language>: installs language
• asdf list-all <language>: shows all available versions of language
• asdf list <language>: shows all installed versions of language
• asdf install <language> <version>:
• asdf current: shows currently enabled languages
• asdf global <language> <version>: enables the chosen version of a language

Installing Node

asdf plugin-add nodejs
asdf list-all nodejs
asdf install nodejs <version>
asdf global nodejs <version>

Installing Erlang

asdf plugin-add erlang
asdf list-all erlang

According to the readme on the ASDF Erlang plugin repo, you can pass configure options through KERL_CONFIGURE_OPTIONS.

export KERL_CONFIGURE_OPTIONS="--disable-debug --without-javac"
asdf install erlang <version>
asdf global erlang <version>

For headless servers, I usually skip Java and wx:

export KERL_CONFIGURE_OPTIONS="--without-wx --without-javac"
asdf install erlang <version>

Old Erlang/OTP versions may need extra flags on newer Ubuntu releases. For example, OTP 21.3 on Ubuntu 24.04 fails to link with modern GCC unless -fcommon is enabled, and Erlang's configure step expects an optimization flag to be present:

export KERL_CONFIGURE_OPTIONS="--without-wx --without-javac"
export CFLAGS="-O2 -g -fcommon"
asdf install erlang 21.3

If an old prebuilt release fails on a modern Ubuntu server with:

libtinfo.so.5: cannot open shared object file

try installing the compatibility library first:

sudo apt install libtinfo5

If libtinfo5 is not available, rebuild the release on the target server with an Erlang version that works on that Ubuntu version.

Installing Elixir

asdf plugin-add elixir
asdf list-all elixir
asdf install elixir <version>
asdf global elixir <version>

Installing Ruby

asdf plugin-add ruby
asdf list-all ruby
asdf install ruby <version>
asdf global ruby <version>

Verify you have what you need

asdf current

Installing the Phoenix Framework

If you're reading this on Alchemist Camp, you're likely using ASDF for Elixir and also want to set up Phoenix:

mix local.hex
mix archive.install hex phx_new 1.8.0 # or whichever version you prefer

Done!

ASDF is a very handy tool for setting up dev machines and keeping the versions of whichever languages you may need. It's a big improvement to have one unified tool over several language specific ones.

ASDF also supports per-project configuration via .tool-versions files and a number of other things not covered in this setup guide.

---

How to fully remove ASDF

If you ever want to fully remove ASDF from your system, all you need to do is delete the directory where you cloned it at the top of the tutorial and the .tool-versions (if any):

rm -rf ~/.asdf/ ~/.tool-versions

You'll probably want to get rid the lines with $HOME/.asdf/asdf.sh and $HOME/.asdf/completions/asdf.bash in your shell config, and that's all there is to it.