Overview of Elixir executables
Tags: elixir, erlang
Published: 2017-11-09 23:29:46

---
title: "Overview of Elixir executables"
published: true
tags: elixir, erlang
cover_image: https://user-images.githubusercontent.com/4419992/32553560-0237e058-c476-11e7-9369-184220961a18.jpg
canonical_url: https://monades.roperzh.com/overview-elixir-executables-escripts/
---

_This post was originally published on [monades.roperzh.com](https://monades.roperzh.com/overview-elixir-executables-escripts//?cm=devto)_

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.

## Escripts

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][erlang-escript-doc], 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][elixir-archives-documentation] (a notable example of this is [Phoenix][phoenix-home]), 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:

- They pollute every Mix project in your system: modules in archives can be accessed by other applications.
- The consumer of the archive has to have Elixir installed to run them.

## 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][elixir-escript-doc] 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:

```elixir
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`.

## Links

- Elixir documentation for [escript][elixir-escript-doc]
- Erlang documentation for [escript][erlang-escript-doc]
- [Video][escripts-talk] and [slides][escripts-slides] of Geoff Cant talk at Erlang Factory 2011

[elixir-escript-doc]: https://hexdocs.pm/mix/Mix.Tasks.Escript.html
[erlang-escript-doc]: http://erlang.org/doc/man/escript.html
[elixir-archives-documentation]: https://hexdocs.pm/mix/Mix.Tasks.Archive.html
[phoenix-home]: http://phoenixframework.org/
[escripts-talk]: https://vimeo.com/23375715
[escripts-slides]: http://www.erlang-factory.com/upload/presentations/350/Escript-GeoffCantErlFSF2011.pdf