Author avatar

AJ Foster

Installing Elixir and Erlang With ASDF

AJ Foster

  • Apr 19, 2021
  • 5 Min read
  • 452 Views
  • Apr 19, 2021
  • 5 Min read
  • 452 Views
Programming Languages
Elixir
Software Development
Languages, Frameworks, and Tools
Web Development

Introduction

Many programming languages regularly release new versions that add or deprecate features, fix bugs, and introduce breaking changes. To help developers switch between versions easily, several language communities have version managers (like NVM for Node.js or Rbenv for Ruby). When you need to switch versions of multiple languages at once, however, the ASDF version manager ensures each project has the environment it needs.

This is especially important in Elixir projects, which require the Erlang runtime. In this guide, you'll learn how to install specific versions of Elixir and Erlang/OTP using the ASDF version manager on macOS or Linux.

Install ASDF

The ASDF version manager is a command-line tool that is available on GitHub. It uses curl and git to install various languages.

Install Prerequisites

To install the curl and git utilities, run:

1
2
brew install coreutils curl git  # on macOS with Homebrew
sudo apt install curl git        # on Linux
shell

You can learn more about Homebrew on macOS here.

Clone ASDF

With the prerequisites installed, now clone the ASDF project:

1
git clone https://github.com/asdf-vm/asdf.git ~/.asdf
shell

If you ever wish to remove ASDF, you can do so by removing .asdf from your home directory and undo the configuration changes described below.

Configure Your Shell

Finally, include ASDF in your shell's configuration. For zsh, add the following to ~/.zshrc:

1
. $HOME/.asdf/asdf.sh
shell

Alternatively, if you use oh-my-zsh, add asdf to your plugin configuration. To include ASDF in your configuration when using a different shell, consult the documentation.

Install Plugins

ASDF uses a plugin system to support multiple languages. For a typical Elixir project, you will need the Elixir and Erlang plugins:

1
2
asdf plugin add erlang
asdf plugin add elixir
shell

If your project requires Node.js, you can also install the nodejs plugin.

Install Erlang/OTP

With ASDF and its plugins installed, you can now install Elixir and Erlang. If your project has a .tool-versions file with entries for elixir and erlang, you can install the correct versions by running the following from inside the project:

1
asdf install
shell

The .tool-versions file is much like .nvmrc and .ruby-version files, except that it lists the names and versions of multiple languages. In general, the names in this file should match the names of the language's plugin (e.g. nodejs for Node.js).

If you do not yet have a .tool-versions file, or want to install Elixir and Erlang globally, use the following to see a list of all available Erlang/OTP versions:

1
2
3
4
5
6
asdf list-all erlang
# ...
23.2
23.2.1
23.2.2
# ...
shell

Unlike other version managers, ASDF requires you to specify a precise version of the language to install. To install version 23.2.1 of Erlang, run:

1
asdf install erlang 23.2.1
shell

Warning: This installation will take some time while it compiles Erlang from source.

Erlang will compile modules based on the available libraries from your system. For example, some features (such as the built-in observer) require wx libraries. You may see messages during the installation about omitted modules, which will not affect the rest of the runtime.

Install Elixir

Once the Erlang runtime is installed, you are ready to install Elixir. To see a list of all available versions, run:

1
2
3
4
5
6
7
asdf list-all elixir
# ...
1.11.2
1.11.2-otp-21
1.11.2-otp-22
1.11.2-otp-23
# ...
shell

Notice that each Elixir release has multiple versions compiled with different major versions of Erlang/OTP. To maximize compatibility between Elixir and the Erlang runtime, choose a -otp-XY version that matches the major version of the runtime you installed in the previous step. For example:

1
asdf install elixir 1.11.2-otp-23
shell

Installing Elixir takes significantly less time than installing Erlang/OTP.

Set Versions

Now that you have Elixir and Erlang/OTP installed, you can save your chosen versions in a project. From the root of the project, run:

1
2
asdf local erlang 23.2.1
asdf local elixir 1.11.2-otp-23
shell

Replace the versions above with those you used during installation. This will create a .tool-versions file in your project, which will instruct ASDF which versions to use. If you'd like to set a global, or default, version, run:

1
2
asdf global erlang 23.2.1
asdf global elixir 1.11.2-otp-23
shell

This will create a .tool-versions file in your home directory. ASDF will use these versions whenever a project doesn't specify versions of its own.

Conclusion

ASDF is a popular version manager for Elixir projects because it manages both Elixir and Erlang versions. Include a .tool-versions file in your projects to help contributors get up-and-running quickly, and don't forget to leverage the -otp-XY versions of Elixir for the best compatibility.

If you'd like to learn more about Elixir and what it can do for your next project, check out Elixir: The Big Picture here on Pluralsight.

5