# Burrito for cross-platform Elixir application distribution

> Burrito packages an Elixir application, its ERTS runtime, and required NIF artifacts into a self-extracting binary for Windows, macOS, and Linux. It suits CLI tools that must run on customer systems without a preinstalled Erlang runtime, but the README explicitly describes the approach as experimental.

**burrito-elixir/burrito** — Wrap your application in a BEAM Burrito!

- Repository: https://github.com/burrito-elixir/burrito
- Stars: 1,450 · Forks: 71
- Language: C
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/burrito-elixir-burrito

## Why Burrito Exists for Elixir CLI Tools

Burrito addresses a distribution problem that appears when an Elixir command-line tool has to run on systems controlled by someone else. The target machine may not have Erlang installed, and the person deploying the tool may not have permission to install a runtime. That rules out the usual assumption that a Mix release can depend on the host's existing BEAM environment.

The README describes a specific operating context: consultants deploy CLI tooling into customer environments running macOS, Linux, or Windows. These tools can also depend on NIFs, which means a single build server may need to produce native artifacts for several supported environments. Burrito is therefore aimed at teams that need one build pipeline for self-contained, cross-platform command-line applications, rather than at developers distributing a server application to a machine they fully control.

The resulting artifact is presented as a Burrito-wrapped binary. It contains the compiled BEAM code, the required ERTS, and compilation artifacts for NIFs built through `elixir-make`. The README also describes automatic updates and licensing checks through a plugin interface, although the detailed implementation is referenced in `lib/versions/release_file.ex`.

This is a narrower goal than a general-purpose installer. Burrito does not present itself as a replacement for package managers or operating-system installers. Its key value is packaging a BEAM application together with the runtime pieces needed to launch it from one portable executable.

## How Burrito Builds the Wrapper and Payload

Burrito has three main parts: a Mix release module, a Zig archiver, and a Zig wrapper. The Mix release module runs during the release process. It gathers the application files, obtains the relevant Erlang VM runtime files, copies the runtime into the release, and invokes the Zig archiver and wrapper.

The archiver turns a directory into a tar-like payload. According to the README, that payload contains the application's compiled BEAM code and the ERTS for the selected target. The archive is Gzip compressed and embedded directly into the wrapper binary. The wrapper is portable cross-platform Zig code, while the payload supplies the platform-specific runtime files.

At launch, the wrapper extracts the payload on the first run into a defined system location, such as AppData or Application Support. It then starts Erlang in embedded mode from Zig. On Unix-like systems, the README says it uses `execve()`. Windows uses a child process instead. Later launches of the same version can use the payload that was extracted previously.

The automatic uninstall behavior is also part of the wrapper's intended lifecycle. The README says that running a new version can uninstall the old payload. That behavior makes Burrito more than a file archiver, but it also means deployment policy should account for files created outside the original download location.

## Build Hosts, ERTS Versions, and NIF Constraints

Burrito supports building for Windows x64, Linux, macOS x86_64, and macOS Apple Silicon. The documented host matrix is more restrictive than the target list. Linux and macOS hosts can target each of those four targets according to the table. Windows is not listed as a supported build host. The README recommends using WSL when the development machine runs Windows.

The build machine also needs tools in `PATH`: Zig 0.15.2, XZ, and 7z for Windows targets. The presence of `7z` is specifically tied to Windows packaging. These prerequisites matter because Burrito is a build-time wrapper generator, not merely a Mix dependency that can package every project from an arbitrary environment.

Burrito provides precompiled Erlang/OTP distributions starting at OTP-25.3 for the supported macOS, Linux, and Windows targets. Projects that require an older runtime are directed to the README section about providing custom Erlang/OTP builds. The README does not establish compatibility for every older ERTS version, so a project with a pinned OTP requirement should confirm that its version has a supported distribution or a valid custom build path.

NIF dependencies create a separate cross-compilation concern. The README specifically mentions compilation artifacts for `elixir-make`-based NIFs and says these must be prepared for supported environments from a common build server. That is a meaningful constraint for CLI tools with native extensions.

## Adding Burrito to a Mix Project

The README's first documented setup action is to add Burrito as a Mix dependency with a version requirement of `~> 1.0`. The snippet belongs in the dependency list of the project's `mix.exs`.

```elixir
defp deps do
  [{:burrito, "~> 1.0"}]
end
```

This is the setup code shown in the README excerpt. It establishes the dependency, but the excerpt does not show the subsequent release configuration, application entry point, build environment variables, or exact command used to produce the first binary. Those details are named as sections in the README, but they are not included here, so no unsupported command or configuration key should be inferred from the dependency declaration.

The practical first-use sequence can therefore be stated only to the extent documented: add the dependency, configure the Mix project according to the full README setup instructions, build on a host listed in the support matrix, and launch the generated Burrito-wrapped binary. The user should first observe that the output runs without requiring a separately installed Erlang runtime on the target system. On first launch, the application should extract its payload into the platform-specific application data location.

Because the README labels the approach experimental, first use should be treated as an integration step. Confirm the exact binary name, release command, target selector, and expected output using the complete project configuration before distributing it.

## Where Burrito Is the Wrong Packaging Choice

Burrito is a poor fit when the target is a Windows build machine. The documented matrix marks Windows hosts as unsupported for every listed target, and the README recommends WSL rather than native Windows builds. It is also a weak choice for a project requiring an older Erlang/OTP release that is not covered by the precompiled distributions and for which the project cannot provide a custom ERTS build.

The model is also less suitable when users require a conventional installer with explicit install-time choices, uninstall controls, or a predictable administrative deployment process. The documented runtime behavior includes first-run extraction, reuse of an extracted payload, and automatic removal of an older version. Those are useful for portable CLI distribution, but they can be surprising where application data directories are locked down or centrally managed.

Burrito should not be confused with a general cross-compilation guarantee. The README documents supported targets and host combinations, but it also calls the approach experimental. A project with native dependencies needs to account for the stated NIF cross-compilation requirement instead of assuming that adding the Mix dependency is sufficient.

For an ordinary Elixir deployment to a controlled server with a managed Erlang installation, a standard Mix release may be simpler. Burrito's distinguishing value is the wrapper plus embedded ERTS model, so it is most relevant when the target environment cannot be provisioned.

## Maintenance, Releases, and the MIT License

Burrito is not archived, and the repository's last push was on 2026-07-24. The release history lists v1.5.0 on 2025-11-03, v1.4.0 on 2025-07-28, and v1.3.0 on 2025-07-28. These dates show recent repository activity and published releases, but they do not by themselves remove the README's experimental warning or guarantee compatibility with every target.

The project is licensed under MIT. That license governs use of the Burrito code, while the runtime distributions and any application dependencies retain their own licensing and distribution terms. A team that embeds ERTS, compiled BEAM code, or native artifacts should review the notices and source obligations for the exact artifacts included in its binary. This is a distribution review rather than a conclusion that all components share one license.

Upgrade planning has two layers: upgrading the `burrito` Mix dependency and rebuilding the application for every supported target. Because the wrapper embeds ERTS and application payload files, a release change can affect both artifact size and compatibility. The README documents automatic old-payload uninstall behavior, but it does not provide a complete rollback procedure. Teams should therefore preserve the previous binary and define how customers will be moved back before relying on automatic version cleanup.

## Conclusion

Adopt Burrito when the deployment target is an Elixir CLI application that needs a self-contained runtime, especially when consultants must install it on customer systems. Do not choose it for an unsupported host combination or when the experimental extraction and wrapper model conflicts with your packaging policy. Before adoption, verify the exact target matrix, the required ERTS version, NIF cross-compilation, extraction location, and the project's current release documentation. Burrito's last repository push was on 2026-07-24, and its releases include v1.5.0 from 2025-11-03.

## FAQ

### What is Burrito used for in Elixir projects?

Burrito packages an Elixir CLI application with its ERTS runtime and native NIF artifacts into a self-extracting binary. The README positions it for cross-platform deployments where the target system may not have Erlang installed.

### Can Burrito build applications for Windows, macOS, and Linux?

Yes. The documented targets are Windows x64, Linux, macOS x86_64, and macOS Apple Silicon. The README does not list Windows as a supported build host and recommends WSL when developing on Windows.

### Does Burrito include the Erlang runtime?

Yes. The wrapper embeds an ERTS distribution with the application payload and extracts it on first launch. Precompiled distributions are documented from OTP-25.3 onward, with custom ERTS builds described for older requirements.

### What limitations does the Burrito README document?

The approach is explicitly described as experimental. The build matrix does not support building on Windows, Windows targets require `7z`, and projects with native NIF dependencies must handle cross-compilation for supported environments.

## Sources

- [burrito-elixir/burrito on GitHub](https://github.com/burrito-elixir/burrito)
- [Issues](https://github.com/burrito-elixir/burrito/issues)
- [License: MIT](https://github.com/burrito-elixir/burrito/blob/main/LICENSE)
- [README](https://github.com/burrito-elixir/burrito/blob/main/README.md)
- [Releases](https://github.com/burrito-elixir/burrito/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/burrito-elixir-burrito