DEV Community

Cover image for IEx: Elixir's Interactive Shell
Muzhawir Amri
Muzhawir Amri

Posted on • Originally published at muzhawir.com

IEx: Elixir's Interactive Shell

#elixir #cli

Starting and Writing Expressions in IEx

Starting an IEx Session and Evaluating Expressions

IEx (Interactive Elixir) is Elixir’s built-in interactive shell or REPL (read–eval–print loop) that allows us to run code directly in the terminal. Through IEx, we can explore language features, read documentation, perform debugging, and more. Since it’s part of Elixir by default, we don’t need to install anything to get started.

To start a session, we simply run the iex command in the terminal:

$ iex
Erlang/OTP 26 [erts-14.0] [source] [64-bit] [smp:20:20] [ds:20:20:10]

Interactive Elixir (1.15.0) - press Ctrl+C to exit (type h() ENTER for help)

iex(1)> # This is where we type Elixir expressions.
Enter fullscreen mode Exit fullscreen mode

When IEx starts, it displays the current Erlang and Elixir runtime versions. After that, the iex(1)> prompt appears, where we can enter expressions. The number in parentheses shows the evaluation count.

Let’s try our first expression:

iex(1)> 1 + 1  ❶
2            ❷
Enter fullscreen mode Exit fullscreen mode

Explanation:

  • ❶ We type the expression 1 + 1.
  • ❷ IEx evaluates it and automatically prints the result: 2.

In Elixir, almost everything is an expression that returns a value. This includes function calls, if, case, and many more.

Multi-line Expressions

IEx also supports writing expressions across multiple lines:

iex(1)> 2 * (    ❶
...(1)>   3 + 1  ❷
...(1)> ) / 4    ❸
2.0              ❹
Enter fullscreen mode Exit fullscreen mode

Explanation:

  • ❶ We begin an expression, but it’s not yet complete due to the open parenthesis.
  • ❷ The ...(1)> prompt appears because IEx is still waiting for us to finish the expression.
  • ❸ Once the expression is complete, we press Enter again to evaluate it.
  • ❹ IEx returns the result: 2.0.

As long as an expression is incomplete, IEx will continue waiting for more input. This feature is useful when we want to write longer expressions in a more readable and structured way.

Reading Documentation in IEx

IEx includes a built-in help feature that lets us read documentation directly from the shell. To start, we just type h:

iex(2)> h

                                  IEx.Helpers

Welcome to Interactive Elixir. You are currently seeing the documentation for
the module IEx.Helpers which provides many helpers to make Elixir's shell more
joyful to work with.

This message was triggered by invoking the helper h(), usually referred to as
h/0 (since it expects 0 arguments).

...... (and so on)
Enter fullscreen mode Exit fullscreen mode

This displays the documentation for the IEx.Helpers module, which provides various helpers to make working with IEx easier.

If we want to view documentation for a specific function, such as IO.puts, we can use h followed by the module and function name:

iex(3)> h IO.puts

                        def puts(device \\ :stdio, item)

  @spec puts(device(), chardata() | String.Chars.t()) :: :ok

Writes item to the given device, similar to write/2, but adds a newline at the
end.

By default, the device is the standard output. It returns :ok if it succeeds.

## Examples

    IO.puts("Hello World!")
    #=> Hello World!

...... (and so on)
Enter fullscreen mode Exit fullscreen mode

From this output, we can see the type spec (the data types accepted by the arguments and the return value), a brief explanation of the IO.puts function, the return value, and example usage.

How We Debug in IEx

One way we can debug in IEx is by using the dbg/1 function. This function prints the expression being evaluated along with its result, shown to the right of the #=> symbol. It helps us trace how data flows through each step.

Here’s a simple example:

iex(14)> dbg(200 + 20.22)
[iex:14: (file)]
200 + 20.22 #=> 220.22

220.22
Enter fullscreen mode Exit fullscreen mode

Here, dbg prints both the expression 200 + 20.22 and its result: 220.22. The final result is still returned as usual.

Since Elixir is a functional language, we often build complex logic by chaining multiple functions together. In this context, dbg becomes especially helpful. This is particularly true when we are working with pipelines. A pipeline is Elixir’s idiomatic way to pass data through a sequence of functions using the pipe operator |>.

We will cover pipelines in more detail in a separate section. For now, we just need to understand that dbg allows us to trace the value at each stage of execution:

iex(16)> -100 |> div(4) |> abs() |> to_string() |> dbg() ❶
[iex:16: (file)]          ❷
-100 #=> -100             ❷
|> div(4) #=> -25         ❷
|> abs() #=> 25           ❷
|> to_string() #=> "25"   ❷

"25"                      ❸
Enter fullscreen mode Exit fullscreen mode

Explanation:

  • ❶ We create a simple pipeline. The initial value -100 is passed through each function in order:

    • div(4) returns -25
    • abs() returns 25
    • to_string() returns "25"
    • dbg/1 prints each stage

  • ❷ This is the output from dbg, showing how the value is transformed at each stage in the pipeline.

  • ❸ The final result of the expression is still returned. In this case, it is "25".

With dbg, we can inspect the execution flow in detail, without needing to insert IO.puts at every step.

Exiting the IEx Session or Viewing Other Options

The fastest way to exit an IEx session is by pressing CTRL+C twice. If we press it only once, IEx will enter BREAK mode and display a menu like the following:

$ iex
Erlang/OTP 27 [erts-15.2] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads
:1] [jit:ns]

Interactive Elixir (1.17.3) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)>
BREAK: (a)bort (A)bort with dump (c)ontinue (p)roc info (i)nfo
       (l)oaded (v)ersion (k)ill (D)b-tables (d)istribution
Enter fullscreen mode Exit fullscreen mode

When in BREAK mode, IEx will wait for our command. Some commonly used options include:

  • (a)bort: Exit the IEx session.
  • (A)bort with dump: Exit while generating a dump for debugging.
  • (c)ontinue: Resume the paused session.

To exit IEx completely, we can either:

  • Press CTRL+C twice in a row, or
  • Press a while in BREAK mode.

Since IEx is a tool we use frequently during development, understanding how to manage sessions early on helps keep our workflow smooth.

References

  • Saša Jurić. (2024). Elixir In Action (3rd ed.). Manning Publications.
  • Elixir. (2024, December 11). IEx [Documentation]. https://hexdocs.pm/iex/IEx.html

Top comments (0)