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.
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 likehttps://asdf-vm.com/
pyenv(and more) all in one! Simply install your language’s plugin!
This means that you install a plugin to manage your versions of Elixir, another plugin for Erlang, a plugin for Node, Ruby, and more.
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?
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.
Follow the instructions for installing it on your platform. Note that there are 3 sections to the install instructions.
asdffor your terminal (the instructions differ)
- Installing common dependencies for the other plugins
After following the instructions, verify
asdf is installed and working in your terminal.
$ asdf --version
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.
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.
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
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.
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
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.
This is the critical point! You need to install the correct version of Elixir that was compiled for the OTP version of Erlang you chose earlier!
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 plugin-update --all
asdf and the Elixir plugin, try listing the versions again using
asdf list-all elixir. You should see the versions which include the
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
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.
Asdf creates a
.tool-versions file in your project directory when you activate a local version.
There are benefits to checking this file in with your project. It can help ensure everyone is using the same version of Elixir and Erlang for the project.
Just be aware that it may also be tracking the version of Node.js, Ruby, Postgres, etc. You may want to discuss it as a team before checking it in as it could override personal preferences.
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.
asdf plugins to consider
The list of available
asdf plugins is quite impressive! Many of them are community contributed. Check it out.
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 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
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!