Overview of Elixir executables

November 7, 2017

Escripts are a good way to distribute self-contained applications/scripts that are executed from the command line by any consumer with the only requirement of having Erlang installed.

Most of the what's described here is valid for Erlang too (escripts are an Erlang feature after all), but the article focuses on escripts from the Elixir perspective.


In this scenario, constructing an executable means to bundle an entire project into a file with an arbitrary extension that can be invoked from the command line and accept arguments. Erlang provides this functionality out of the box with escripts, and Elixir leverages this.

Escripts allows you to package an entire OTP application, including its dependencies into a single executable file, every time an escript boots, triggers an independant Erlang node, therefore everything you can do in Erlang (and thus on Elixir) can be done in escripts.

A few words on archives

You may find Elixir libraries that support the option to be installed globally and execute commands in the command-line via archives (a notable example of this is Phoenix), so it's worth to clarify what an archive is, and why you should always try to stick with escripts whenever possible.

An Erlang archive is a zip file with extension .ez. This file can contain applications or part of applications as well as its compiled BEAM files, but do not include the application dependencies.

In Elixir, archives are installed with Mix, and they have several peculiarities:

Managing escripts using Mix

Mix comes with a bunch of built-in tasks to help you build, manage and distribute escripts, which are well documented in the official documentation. Here's a summary of the most used commands:

mix escript

Lists the escripts you have installed, it's just a directory listing of ~/.mix/escripts/

mix escript.build

Compiles a project and its dependencies and packages them in a escript. Before invoking mix escript.build, it's only necessary to define a :escript key with a :main_module option in your mix.exs file:

escript: [main_module: MyApp.CLI]

mix escript.install

If no argument is provided, will try to install the project in the current folder, otherwise, the argument can be a local path or a URL to a prebuilt escript, a Git repository (git <url>), a GitHub repository (github <url>), or a Hex package (hex <package_name>).

Installing an escript means compiling and placing the binary in ~/.mix/escripts.