Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 48 ยท Getting Started

Installing Elixir and Using IEx

Install Erlang/OTP and Elixir on Windows, macOS or Linux, start the IEx shell, run .exs scripts and check versions with mix --version. Includes a REPL stand-in.

To run Elixir on your own computer you need two things: Erlang/OTP, which provides the BEAM virtual machine, and Elixir itself, which provides the compiler, the standard library and the tools iex, elixir and mix. Most installers and package managers set up both together.

This lesson shows common ways to install them, how to check that everything works, how to use the interactive shell IEx, and how to run a script file. Everything here happens in your terminal, so the commands are read-only on this site. After the install section, two JavaScript stand-ins let you practice the feel of a shell session and of version requirements.

Installing Erlang and Elixir

Pick the route that suits your system. Commands and package names change over time, so the official install page is the final authority; these are the usual paths.

macOS with Homebrew installs Erlang as a dependency:

Terminal
brew install elixir

Windows has an official installer that bundles a matching Erlang; download it from the Elixir website's install page. Version managers such as mise also work on Windows.

Debian and Ubuntu can install from the distribution packages, but those are often a few versions behind:

Terminal
sudo apt update
sudo apt install elixir erlang

Any system can use a version manager, which is the best choice if you work on several projects. The popular ones are asdf and mise. They install Erlang and Elixir side by side and let each project pin its own versions in a file such as .tool-versions:

Terminal
asdf plugin add erlang
asdf plugin add elixir
asdf install erlang latest
asdf install elixir latest

Elixir versions are built for specific Erlang/OTP versions. If you install them separately, check that the Elixir release you pick supports your OTP release. Version managers and installers usually take care of this.

Checking the installation

Open a new terminal and ask each tool for its version:

Terminal
elixir --version

The output has two parts, the Erlang/OTP line with the erts (runtime) version, and the Elixir line:

TEXT
Erlang/OTP 28 [erts-16.0] [64-bit] [smp:8:8] [jit]

Elixir 1.19.0 (compiled with Erlang/OTP 28)

Your numbers will differ, and that is fine. What matters is that both lines appear. Then check Mix, the build tool that ships with Elixir:

Terminal
mix --version

It prints its own Mix version followed by the same Elixir information. If a command is "not found", the folder that holds the programs is not on your PATH. Close and reopen the terminal first; if that does not help, add the install folder to PATH (the installer's finish screen or the version manager's docs say where it is).

Meet IEx

IEx stands for Interactive Elixir. It is a REPL: a shell that reads one expression, evaluates it, prints the result and waits for more. It is the best place to try small ideas. Start it with:

Terminal
iex

You see a banner and a prompt with a counter, iex(1)>:

ELIXIR
iex(1)> 1 + 2
3
iex(2)> name = "Ana"
"Ana"
iex(3)> "Hello, " <> name
"Hello, Ana"
iex(4)> String.upcase(name)
"ANA"

Every line you type is an expression, and IEx prints its value. Variables you create stay available for the rest of the session. A few other tricks make IEx a great learning tool:

  • h String.upcase prints the documentation of a function; h Enum shows a whole module's docs.
  • v() returns the previous result and v(2) returns the result of line 2.
  • Press Tab after typing String. to see every function in the module.
  • i name prints information about a value: its type, size and protocols.
  • clear clears the screen, recompile rebuilds a Mix project, and exit, or pressing Ctrl+C twice, leaves the shell.

IEx can also load code from a Mix project with iex -S mix, so you can call your own modules while you develop. Mix projects explains that.

Here is a stand-in for the prompt. It is a few lines of JavaScript that evaluates simple arithmetic and keeps a numbered history, so you can see how v() and the counter behave. It is not Elixir; real IEx understands the full language.

JS Stand-in: a numbered REPL with history

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that results pile up in history, and that v() simply reads from it. In real IEx, the same idea lets you reuse an answer without retyping or assigning it.

Running scripts

You do not have to type everything into IEx. Save code in a file and give it to the elixir command. Elixir uses two file extensions:

  • .exs is an Elixir script. It is compiled in memory and run immediately, with nothing written to disk. Use it for small programs, tests and configuration.
  • .ex is Elixir source meant to be compiled into .beam files, usually by Mix as part of a project.

Create hello.exs with one line:

ELIXIR
IO.puts("Hello from a script!")

Run it:

Terminal
elixir hello.exs
TEXT
Hello from a script!

When the script finishes, the program ends. The next lesson, your first Elixir program, builds on this. You can also run a one-liner without a file, using -e:

Terminal
elixir -e 'IO.puts(1 + 1)'

If you use Windows PowerShell, wrap the expression in double quotes and use single quotes inside it, because the two shells treat quotes differently.

To start IEx and run a script first so its definitions are available in the shell, use iex hello.exs.

Versions and requirements

Projects state which Elixir versions they work with. In a Mix project's mix.exs you will see a line like elixir: "~> 1.15". The ~> operator means "this version or newer, but not the next major (or minor) step": ~> 1.15 allows 1.15.0 up to, but not including, 2.0.0; ~> 1.15.2 allows 1.15.2 up to, but not including, 1.16.0.

The stand-in below implements that rule. It is a simplified model of the real check that Mix performs with the Version module.

JS Stand-in: what does ~> allow?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common problems

  • elixir: command not found: the install folder is not on PATH, or the terminal was opened before installing. Reopen the terminal.
  • Mismatched OTP: a very new Elixir on an old Erlang (or the other way round) can fail at startup. Check the compatibility notes for your Elixir release.
  • Strange characters in IEx on Windows: use a modern terminal such as Windows Terminal. The old console can mis-draw UTF-8 text.
  • Two versions installed: run which elixir (macOS and Linux) or where elixir (Windows) to see which one wins.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What are the two things you need installed to run Elixir?

    Elixir compiles to BEAM bytecode, so it needs Erlang/OTP for the virtual machine plus Elixir for the compiler and tools.
  2. 2. What does IEx do?

    IEx is Elixir's REPL. It reads an expression, prints the value and keeps variables for the rest of the session.
  3. 3. What is the difference between a .ex and a .exs file?

    Scripts (.exs) are compiled in memory and run at once. Regular source (.ex) is compiled into .beam files.
  4. 4. Which versions does the requirement ~> 1.15 allow?

    The ~> operator allows the given version and newer ones up to, but not including, the next major version when you write two parts.

Summary

  • Install Erlang/OTP and Elixir with an installer, a package manager or a version manager such as asdf or mise.
  • elixir --version and mix --version confirm the install.
  • iex starts the interactive shell; use h, v(), i and Tab completion.
  • .exs files are scripts you run with elixir file.exs; .ex files are compiled source.
  • Projects declare compatible versions with requirements such as ~> 1.15.

Next: Your First Elixir Program