Elixir's interactive shell.

Some of the functionalities described here will not be available depending on your terminal. In particular, if you get a message saying that the smart terminal could not be run, some of the features described here won't work.

Helpers

IEx provides a bunch of helpers. They can be accessed by typing h() into the shell or as a documentation for the IEx.Helpers module.

Autocomplete

To discover a module's public functions or other modules, type the module name followed by a dot, then press tab to trigger autocomplete. For example:

Enum.

A module may export functions that are not meant to be used directly: these functions won't be autocompleted by IEx. IEx will not autocomplete functions annotated with @doc false, @impl true, or functions that aren't explicitly documented and where the function name is in the form of __foo__.

Autocomplete is available by default on Windows shells from Erlang/OTP 26. In earlier versions, you may need to pass the --werl option when starting IEx, such as iex --werl (or iex.bat --werl if using PowerShell). --werl may be permanently enabled by setting the IEX_WITH_WERL environment variable to 1.

Encoding and coloring

IEx expects inputs and outputs to be in UTF-8 encoding. This is the default for most Unix terminals but it may not be the case on Windows. If you are running on Windows and you see incorrect values printed, you may need to change the encoding of your current session by running chcp 65001 before calling iex (or before calling iex.bat if using PowerShell).

Similarly, ANSI coloring is enabled by default on most Unix terminals. They are also available on Windows consoles from Windows 10 and on Erlang/OTP 26 or later. For earlier Erlang/OTP versions, you can explicitly enable it for the current user in the registry by running the following command:

$ reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1

After running the command above, you must restart your current console.

Shell history

It is possible to get shell history by passing some options that enable it in the VM. This can be done on a per-need basis when starting IEx:

$ iex --erl "-kernel shell_history enabled"

If you would rather enable it on your system as a whole, you can use the ERL_AFLAGS environment variable and make sure that it is set accordingly on your terminal/shell configuration.

On Unix-like / Bash:

$ export ERL_AFLAGS="-kernel shell_history enabled"

On Windows:

$ set ERL_AFLAGS "-kernel shell_history enabled"

On Windows 10 / PowerShell:

$ $env:ERL_AFLAGS = "-kernel shell_history enabled"

Expressions in IEx

As an interactive shell, IEx evaluates expressions. This has some interesting consequences that are worth discussing.

The first one is that the code is truly evaluated and not compiled. This means that any benchmarking done in the shell is going to have skewed results. So never run any profiling nor benchmarks in the shell.

Second, IEx allows you to break an expression into many lines, since this is common in Elixir. For example:

iex(1)> "ab
...(1)> c"
"ab\nc"

In the example above, the shell will be expecting more input until it finds the closing quote. Sometimes it is not obvious which character the shell is expecting, and the user may find themselves trapped in the state of incomplete expression with no ability to terminate it other than by exiting the shell.

For such cases, there is a special break-trigger (#iex:break) that when encountered on a line by itself will force the shell to break out of any pending expression and return to its normal state:

iex(1)> ["ab
...(1)> c"
...(1)> "
...(1)> ]
...(1)> #iex:break
** (TokenMissingError) iex:1: incomplete expression

Pasting multiline expressions into IEx

IEx evaluates its input line by line in an eager fashion. If at the end of a line the code seen so far is a complete expression, IEx will evaluate it at that point.

iex(1)> [1, [2], 3]
[1, [2], 3]

To prevent this behaviour breaking valid code where the subsequent line begins with a binary operator, such as |>/2 or ++/2 , IEx automatically treats such lines as if they were prepended with IEx.Helpers.v/0, which returns the value of the previous expression, if available.

iex(1)> [1, [2], 3]
[1, [2], 3]
iex(2)> |> List.flatten()
[1, 2, 3]

The above is equivalent to:

iex(1)> [1, [2], 3]
[1, [2], 3]
iex(2)> v() |> List.flatten()
[1, 2, 3]

If there are no previous expressions in the history, the pipe operator will fail:

iex(1)> |> List.flatten()
** (RuntimeError) v(-1) is out of bounds

If the previous expression was a match operation, the pipe operator will also fail, to prevent an unsolicited break of the match:

iex(1)> x = 42
iex(2)> |> IO.puts()
** (SyntaxError) iex:2:1: pipe shorthand is not allowed immediately after a match expression in IEx. To make it work, surround the whole pipeline with parentheses ('|>')
    |
  2 | |> IO.puts()
    | ^

Note, however, the above does not work for +/2 and -/2, as they are ambiguous with the unary +/1 and -/1:

iex(1)> 1
1
iex(2)> + 2
2

The BREAK menu

Inside IEx, hitting Ctrl+C will open up the BREAK menu. In this menu you can quit the shell, see process and ETS tables information and much more.

Exiting the shell

There are a few ways to quit the IEx shell:

• via the BREAK menu (available via Ctrl+C) by typing q, pressing enter
• by hitting Ctrl+C, Ctrl+C
• by hitting Ctrl+\

If you are connected to remote shell, it remains alive after disconnection.

dbg and breakpoints

IEx integrates with Kernel.dbg/2 and introduces a backend that can pause code execution. To enable it, you must pass --dbg pry:

$ iex --dbg pry

For example, take the following function:

def my_fun(arg1, arg2) do
  dbg(arg1 + arg2)
  ... implementation ...
end

When the code is executed with iex (most often by calling iex --dbg pry -S mix), it will ask you permission to use "pry". If you agree, it will start an IEx shell in the context of the function above, with access to its variables, imports, and aliases. However, you can only access existing values, it is not possible to access private functions nor change the execution itself (hence the name "pry").

When using |> dbg() at the end of a pipeline, you can pry each step of the pipeline. You can type n whenever you want to jump into the next pipe. Type continue when you want to execute all of the steps but stay within the pried process. Type respawn when you want to leave the pried process and start a new shell.

Alternatively, you can start a pry session directly, without dbg/2 by calling IEx.pry/0.

IEx also allows you to set breakpoints to start pry sessions on a given module, function, and arity you have no control of via IEx.break!/4. Similar to pipelines in dbg(), IEx.break!/4 allows you to debug a function line by line and access its variables. However, breakpoints do not contain information about imports and aliases from the source code.

When using dbg or breakpoints with tests, remember to pass the --trace to mix test to avoid running into timeouts:

$ iex -S mix test --trace
$ iex -S mix test path/to/file:line --trace

The User switch command

Besides the BREAK menu, one can type Ctrl+G to get to the User switch command menu. When reached, you can type h to get more information.

In this menu, developers are able to start new shells and alternate between them. Let's give it a try:

User switch command
 --> s 'Elixir.IEx'
 --> c

The command above will start a new shell and connect to it. Create a new variable called hello and assign some value to it:

hello = :world

Now, let's roll back to the first shell:

User switch command
 --> c 1

Now, try to access the hello variable again:

hello
** (CompileError) undefined variable "hello"

The command above fails because we have switched shells. Since shells are isolated from each other, you can't access the variables defined in one shell from the other one.

The User switch command can also be used to terminate an existing session, for example when the evaluator gets stuck in an infinite loop or when you are stuck typing an expression:

User switch command
 --> i
 --> c

The User switch command menu also allows developers to connect to remote shells using the r command. A topic which we will discuss next.

Remote shells

IEx allows you to connect to another node in two fashions. First of all, we can only connect to a shell if we give names both to the current shell and the shell we want to connect to.

Let's give it a try. First, start a new shell:

$ iex --sname foo
iex(foo@HOST)1>

The string between the parentheses in the prompt is the name of your node. We can retrieve it by calling the node/0 function:

iex(foo@HOST)1> node()
:"foo@HOST"
iex(foo@HOST)2> Node.alive?()
true

For fun, let's define a simple module in this shell too:

iex(foo@HOST)3> defmodule Hello do
...(foo@HOST)3>   def world, do: "it works!"
...(foo@HOST)3> end

Now, let's start another shell, giving it a name as well:

$ iex --sname bar
iex(bar@HOST)1>

If we try to dispatch to Hello.world/0, it won't be available as it was defined only in the other shell:

iex(bar@HOST)1> Hello.world()
** (UndefinedFunctionError) undefined function Hello.world/0

However, we can connect to the other shell remotely. Open up the User switch command prompt (Ctrl+G) and type:

User switch command
 --> r 'foo@HOST' 'Elixir.IEx'
 --> c

Now we are connected into the remote node, as the prompt shows us, and we can access the information and modules defined over there:

iex(foo@HOST)1> Hello.world()
"it works!"

In fact, connecting to remote shells is so common that we provide a shortcut via the command line as well:

$ iex --sname baz --remsh foo@HOST

Where "remsh" means "remote shell". In general, Elixir supports:

• remsh from an Elixir node to an Elixir node
• remsh from a plain Erlang node to an Elixir node (through the ^G menu)
• remsh from an Elixir node to a plain Erlang node (and get an erl shell there)

Connecting an Elixir shell to a remote node without Elixir is not supported.

The .iex.exs file

When starting, IEx looks for a local .iex.exs file (located in the current working directory), then for a global .iex.exs file located inside the directory pointed by the IEX_HOME environment variable (which defaults to ~) and loads the first one it finds (if any).

The code in the chosen .iex.exs file is evaluated line by line in the shell's context, as if each line were being typed in the shell. For instance, any modules that are loaded or variables that are bound in the .iex.exs file will be available in the shell after it has booted.

Take the following .iex.exs file:

# Load another ".iex.exs" file
import_file("~/.iex.exs")

# Import some module from lib that may not yet have been defined
import_if_available(MyApp.Mod)

# Print something before the shell starts
IO.puts("hello world")

# Bind a variable that'll be accessible in the shell
value = 13

Running IEx in the directory where the above .iex.exs file is located results in:

$ iex
Erlang/OTP 24 [...]

hello world
Interactive Elixir - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> value
13

It is possible to load another file by supplying the --dot-iex option to IEx. See iex --help.

In case of remote nodes, the location of the .iex.exs files are taken relative to the user that started the application, not to the user that is connecting to the node in case of remote IEx connections.

Configuring the shell

There are a number of customization options provided by IEx. Take a look at the docs for the IEx.configure/1 function by typing h IEx.configure/1.

Those options can be configured in your project configuration file or globally by calling IEx.configure/1 from your ~/.iex.exs file. For example:

# .iex.exs
IEx.configure(inspect: [limit: 3])

Now run the shell:

$ iex
Erlang/OTP 24 [...]

Interactive Elixir - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> [1, 2, 3, 4, 5]
[1, 2, 3, ...]