Install Elixir using asdf

There are a number of ways to install Elixir. However, to get the best experience, there are some non-obvious things you need to pay attention to. Here I’ll walk you through how to do this on MacOS and Linux using the asdf version manager project.

Why is this important? Many people (myself included) have unknowingly installed less-compatible versions of Erlang and Elixir, then tried to use VS Code with the ElixirLS extension and had a bad time. Things don’t work correctly, the extension crashes, etc. This guide helps you setup a solid Elixir and Erlang foundation for doing Elixir development.

What is asdf?

From the asdf-vm website, this is their short description.

Manage multiple runtime versions with a single CLI tool, extendable via plugins. asdf-vm 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!

https://asdf-vm.com/

This means that you install a plugin to manage your versions of Elixir, another plugin for Erlang, a plugin for Node, Ruby, and more.

Once asdf if setup, it is a very easy way to manage multiple versions of Elixir. Additionally, as you change directories in the console and move from one project to another, the version of Elixir, Node, Ruby, etc. can be set for each project and will be used when in that directory!

What OS Platforms are supported?

Note that asdf-vm works on MacOS and Linux. It does not support Windows.

If you are using Windows 10, consider installing Ubuntu using Microsoft’s Windows Subsystem for Linux. Here’s a guide to walk you through the process. This gives you a proper Bash shell in an Ubuntu terminal. So the asdf-vm installation instructions for Ubuntu apply to it.

There may other methods to get a good, stable Elixir system installed on Windows. The principles are the same. The versions of Erlang and Elixir must be compatible and other supporting software libraries like WxWidgets are needed to enable features like Observer.

Install asdf

Follow the instructions for installing it on your platform. Note that there are 3 sections to the install instructions.

1. Installing asdf itself
2. Installing asdf for your terminal (the instructions differ)
3. Installing common dependencies for the other plugins

After following the instructions, verify asdf is installed and working in your terminal.

$ asdf --version
v0.7.4

By itself, asdsf doesn’t do much. Really it’s the foundation for installing and running plugins and hooking into your terminal.

For Elixir development, we need to install both Erlang and Elixir.

An important note on versions

Before we go any further with actually installing Erlang and Elixir, it is important to understand how the versions of the two work together… or not.

The version of Erlang is often referred to as the OTP version. The version of Elixir used must be compiled specifically for the version of Erlang in use.

$ elixir -v

Note the first line Erlang/OTP 22 must match the Erlang version that Elixir was compiled against. If they do not match, you may encounter issues.

Knowing you can use elixir -v to see both versions helps you quickly tell when you have compatible versions being used together.

Install Erlang

First we need to install the asdf plugin that installs Erlang and manages the versions for us.

The following command adds the Erlang plugin.

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

Before installing Erlang, make sure you follow the directions on the plugin page for your platform. To get the best experience, there are additional OS dependencies that should be installed. Once the dependencies are installed, you are ready to install Erlang.

For the best Elixir experience, there are additional OS dependencies for Erlang to install.

UPDATE: As of Elixir 1.11, support for Erlang Docs was added. The docs are accessed through IEx. However, Erlang must be compiled and installed with documentation enabled. Check out this post to see how to set that up.

To install Erlang, you first need to decide which version you need. If you don’t have any specific project needs, then select the latest version. To list the available versions, use the asdf list-all erlang command. It returns a long list. Truncated output is included below.

$ asdf list-all erlang
...
22.0
22.0.1
22.0.2
22.0.3
22.0.4
22.0.5
22.0.6
22.0.7
22.0-rc1
22.0-rc2
22.0-rc3
22.1
22.1.1
22.1.2
22.1.3
22.1.4
22.1.5
22.1.6
22.1.7

The latest version at the time of this writing is 22.1.7. To install version 22.1.7, use the following command:

$ asdf install erlang 22.1.7
Downloading OTP-22.1.7.tar.gz to 
...
Extracting source code
Building Erlang/OTP 22.1.7 (asdf_22.1.7), please wait...
...

Erlang 22.1.7 has been installed. Activate globally with:

    asdf global erlang 22.1.7

Activate locally in the current folder with:

    asdf local erlang 22.1.7

This downloads the source and compiles it on your machine. This will take some time.

The final output tells you how to set the Erlang version globally or locally. Locally means for the current directory and globally means for your logged in user. More on that after we get Elixir installed.

Install Elixir

First the asdf Elixir plugin needs to be installed. The following command performs the install:

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

Now you need to decide which version of Elixir to install. Again, unless you have specific project needs, go with the latest version. To get a list of available versions, use the asdf list-all elixir command. It returns a long list. Truncated output is included below.

$ asdf list-all elixir
...
1.9.0
1.9.0-otp-20
1.9.0-otp-21
1.9.0-otp-22
1.9.1
1.9.1-otp-20
1.9.1-otp-21
1.9.1-otp-22
1.9.2
1.9.2-otp-20
1.9.2-otp-21
1.9.2-otp-22
1.9.3
1.9.3-otp-20
1.9.3-otp-21
1.9.3-otp-22
1.9.4
1.9.4-otp-20
1.9.4-otp-21
1.9.4-otp-22
master
master-otp-21
master-otp-22

The most important thing to note here is the version with the otp-22 release included. If you don’t see the OTP version displayed, then you have an older asdf install and you need to update your asdf Elixir plugin.

Install the matching Elixir OTP version

If you installed Erlang 22.x, then install the matching Elixir version 1.9.4-otp-22. Likewise, if you installed Erlang 20.x, then install the matching Elixir version for that OTP release.

If you don’t see the OTP version information in the list, update asdf and your asdf Elixir plugin first.

Update asdf and your asdf Elixir plugin

Running the command asdf by itself displays the available commands. The commands to use for updating are these:

• asdf update
• asdf plugin-update --all

After updating asdf and the Elixir plugin, try listing the versions again using asdf list-all elixir. You should see the versions which include the -otp-XX.

Install your Elixir version

Installing the version of Elixir you want is much faster than it was for Erlang. The Elixir versions are pre-built binaries. Install your desired version now!

asdf install elixir 1.9.4-otp-22

Check your Elixir version using elixir -v.

$ elixir -v
Erlang/OTP 22 [erts-10.4.4] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:1] [hipe]

Elixir 1.9.1 (compiled with Erlang/OTP 22)

Wait! That isn’t the new version! We need to use asdf to activate the version.

Activating your Elixir and Erlang versions

Although we installed the versions we want, they aren’t yet activated. There are two ways to activate a version.

• global – used everywhere by your user
• local – used specifically for the current directory

Set the global config to be used by default.

$ asdf global erlang 22.1.7
$ asdf global elixir 1.9.4-otp-22

Now check your Elixir version.

$ elixir -v
Erlang/OTP 22 [erts-10.5.5] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:1] [hipe]

Elixir 1.9.4 (compiled with Erlang/OTP 22)

For up-to-date information on how asdf works and the other features, refer to the project website.

Cleaning up after the change

Assuming you already had Elixir and Erlang installed and following this guide you changed your versions, then it is best to clean your project’s build artifacts. Otherwise you’re likely to get strange compilation errors. This is a good idea to do whenever you change your active Elixir or Erlang versions.

Use the following command.

mix do clean, compile

If you are using VS Code as your editor and installed the ElixirLS extension as I suggest, then you have an .elixirls/ directory in your project. This contains compiled code for your project that ElixirLS uses to give code insight. To avoid potential issues, delete that directory to get a clean start.

Trying out master

Did you notice when you run asdf list-all elixir that the last Elixir version listed is master? Installing Elixir’s master branch is an easy way to test out Elixir’s pre-released features. After playing on the master branch, you can easily change back to the Elixir version you do day-to-day development with.

Other asdf plugins to consider

The list of available asdf plugins is quite impressive! Many of them are community contributed. Check it out.

Full list of plugins

There may be several that interest you. I’ll just point out some.

If you are already using a language version manager like nvm for Node.js or rvm for Ruby, then just know that asdf can replace both of those for you.

• asdf Node.js plugin – Most web applications need some javascript.
• asdf Postgres plugin – Yes… the database. Ever needed to support specific versions? This offers another way to do that.
• asdf Flutter plugin – For cross-platform native mobile development
• asdf Ruby plugin – In case you also manage Ruby projects
• asdf Python plugin – In case you also manage Python projects

When installing a plugin, it may be worth paying attention to the Github account that maintains it. The Elixir and Erlang plugins are maintained by the asdf-vm team.

Ready, set, code!

With a solid install of Elixir and Erlang, you are ready to get your coding environment setup too. If you’d like some recommendations, check out my guide on setting up VS Code for Elixir development.

Are you learning Elixir? Check out my courses to help you make the mental shifts faster and easier!