Introduction
This article is part of a beginner series where I document my personal journey learning Elixir and taking my first real steps in its ecosystem.
I recently came from Node.js, where setting up a development environment is usually very simple: install Node, get npm, add some VS Code extensions, and you're ready to go.
With Elixir, the process is not hard, but I had a tough time finding a clear step-by-step guide. I ended up skipping important steps, which later caused a lot of unnecessary problems to fix.
So in this guide, I’ll walk you through how to set up your Elixir environment from scratch using ASDF.
Note: I’m using Linux Mint, but the same process applies to most Linux distributions with small adjustments.
What Is ASDF and Why Use It?
The first thing we’ll install is a small but very powerful tool called ASDF.
[ASDF][1] is a version manager that allows you to install and manage multiple versions of languages and runtimes — including Erlang and Elixir — on the same machine.
That means:
- You can easily switch between versions
- Projects can define their own required versions
- Your global system stays clean
Grab some coffee ☕ and let’s start.
Step 1: Installing ASDF
First, go to the official website:
https://asdf-vm.com/
Click on Get Started and check the installation method for your operating system.
On Linux Mint (and Ubuntu-based distros), make sure you have curl and git installed:
sudo apt install curl git
Now clone the ASDF repository:
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.9.0
Shell Integration (Very Important)
This step is critical so your terminal can recognize the asdf command.
If you use Oh My Zsh
Follow the plugin instructions from:
https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf
Basically, add this line to your ~/.zshrc file:
plugins=(git asdf)
Then close and reopen your terminal.
If you use Bash
Add these two lines to your ~/.bashrc file:
. $HOME/.asdf/asdf.sh
. $HOME/.asdf/completions/asdf.bash
Restart the terminal.
Verify Installation
Run:
asdf --version
You should see something similar to:
v0.9.0-9ee24a3
Step 2: Installing the Erlang Plugin
With ASDF installed, we can now install plugins. Let’s start with Erlang.
asdf plugin-add erlang
Installing System Dependencies
Before compiling Erlang, we must install some required packages.
For Linux Mint / Ubuntu 20-based systems:
sudo apt-get -y install build-essential autoconf m4 libncurses5-dev libwxgtk3.0-gtk3-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils libncurses-dev openjdk-11-jdk
These dependencies are listed in the official ASDF Erlang plugin repository:
https://github.com/asdf-vm/asdf-erlang
Step 3: Installing Erlang
List all available Erlang versions:
asdf list-all erlang
Install the latest stable version at the time of writing:
asdf install erlang 24.2.1
Tip: This step takes time and may look frozen. That’s normal. Be patient.
Set Erlang as Global Version
asdf global erlang 24.2.1
Test Erlang
erl
If you see the Erlang shell, everything is working.
Exit with Ctrl + C twice.
Step 4: Installing Elixir with ASDF
Now let’s install the Elixir plugin:
asdf plugin-add elixir
List available versions:
asdf list-all elixir
Since we installed Erlang OTP 24, we must install an Elixir version built for OTP 24.
At the time of writing:
asdf install elixir 1.13.3-otp-24
Set it globally:
asdf global elixir 1.13.3-otp-24
Test Elixir
Start IEx:
iex
You should see the Elixir interactive shell.
Hello World
Inside IEx:
IO.puts("Hello World")
Welcome to Elixir
Step 5: Using Livebook for Experiments and Notes
Livebook is similar to Jupyter Notebook for Python.
It allows you to:
- Write executable Elixir code
- Document your learning
- Save notebooks as Markdown
Installing Livebook
Go to the official repository:
https://github.com/livebook-dev/livebook
Since Elixir is already installed globally, run:
mix escript.install hex livebook
Confirm installation when prompted.
Because we’re using ASDF, we must refresh shims:
asdf reshim
Start Livebook:
livebook server
Now open your browser and go to:
http://localhost:8080
Conclusion
In this article, we covered how to:
- Install ASDF
- Install Erlang
- Install Elixir
- Set up Livebook locally
This setup gives you a solid and flexible environment to start learning and building with Elixir.
In the next articles of this series, we’ll finally start writing real Elixir code.
See you in the next post ⚡
