Mix v1.5.0-dev Mix.Tasks.Escript.Build

Builds an escript for the project.

An escript is an executable that can be invoked from the command line. An escript can run on any machine that has Erlang installed and by default does not require Elixir to be installed, as Elixir is embedded as part of the escript.

This task guarantees the project and its dependencies are compiled and packages them inside an escript.

Note: escripts do not support projects and dependencies that need to store or read artifacts from the priv directory.

Command line options

  • --force - forces compilation regardless of modification times
  • --no-compile - skips compilation to .beam files


The following option must be specified in your mix.exs under :escript key:

  • :main_module - the module to be invoked once the escript starts. The module must contain a function named main/1 that will receive the command line arguments as binaries.

The remaining options can be specified to further customize the escript:

  • :name - the name of the generated escript. Defaults to app name.

  • :path - the path to write the escript to. Defaults to app name.

  • :app - the app to start with the escript. Defaults to app name. Set it to nil if no application should be started.

  • :strip_beam - if true strip BEAM code in the escript to remove chunks unnecessary at runtime, such as debug information and documentation. Defaults to true.

  • :embed_elixir - if true embed Elixir and its children apps (ex_unit, mix, etc.) mentioned in the :applications list inside the application/0 function in mix.exs.

    Defaults to true for Elixir projects, false for Erlang projects.

    Note: if you set this to false for an Elixir project, you will have to add paths to Elixir’s ebin directories to ERL_LIBS environment variable when running the resulting escript, in order for the code loader to be able to find :elixir application and its children applications (if they are used).

  • :shebang - shebang interpreter directive used to execute the escript. Defaults to "#! /usr/bin/env escript\n".

  • :comment - comment line to follow shebang directive in the escript. Defaults to "".

  • :emu_args - emulator arguments to embed in the escript file. Defaults to "".

There is one project-level option that affects how the escript is generated:

  • language: :elixir | :erlang - set it to :erlang for Erlang projects managed by mix. Doing so will ensure Elixir is not embedded by default. Your app will still be started as part of escript loading, with the config used during build.


defmodule MyApp.Mixfile do
  use Mix.Project

  def project do
    [app: :my_app,
     version: "0.0.1",
     escript: escript()]

  def escript do
    [main_module: MyApp.CLI]

defmodule MyApp.CLI do
  def main(_args) do
    IO.puts("Hello from MyApp!")



A task needs to implement run which receives a list of command line args


run(OptionParser.argv) :: :ok | :noop

A task needs to implement run which receives a list of command line args.

Callback implementation for Mix.Task.run/1.