The HashNuke Heroku buildpack makes the Elixir version a config line

The version matrix is the reason this buildpack exists

Heroku stacks move, and an application that pins its runtime does not. This buildpack exists to give an Elixir application control over which Erlang and Elixir it runs on, and the README is candid about why that is harder than it sounds. Although the maintainers try to support as many old Elixir and Erlang releases as possible, it is sometimes difficult because there is a matrix of three variables involved: the Erlang version, the Elixir version and the Heroku stack. Both runtimes come prebuilt rather than compiled from source, with the list of prebuilt Erlang packages published per stack and the list of Elixir releases and branches taken from the Elixir project itself. The README also points out that you have to choose an Elixir and an Erlang version that are compatible with one another, which is a separate decision from picking either of them.

Prebuilt binaries and the stacks they are published for

The prebuilt Erlang packages are listed per stack, with separate build indexes for the gigalixir-20 and heroku-20 stacks on Ubuntu 20.04, for the heroku-22 stacks on Ubuntu 22.04, and a general list of other versions maintained in a separate repository. On the Elixir side you can point at a release such as 1.0.4 or 1.0.3, or at a prebuilt branch such as master or v1.7, with the full release and branch lists linked from the Elixir project. The buildpack also consolidates protocols, supports Hex and rebar, and caches Hex packages, Mix dependencies and downloads, which is the difference between a deploy that reuses a cache and one that fetches the world on every push. Two features exist for teams that want their build to fail loudly, a `hook_compile` option that can be set to compile with warnings as errors, and Heroku CI support, with the tapex tool added to a project so that test runs are visible on Heroku.

Configuration is a bash file in the app root

Every option lives in a file called `elixir_buildpack.config` in the root of your application, and the README states that the file's syntax is bash. Anything you do not specify falls back to the default from the buildpack's own copy of the same file. The full set of options is published in the README, and the file looks like this:

# Erlang version
erlang_version=18.2.1

# Elixir version
elixir_version=1.2.0

# Always rebuild from scratch on every deploy?
always_rebuild=false

# Create a release using `mix release`? (requires Elixir 1.9)
release=true

# A command to run right before fetching dependencies
hook_pre_fetch_dependencies="pwd"

# A command to run right before compiling the app (after elixir, .etc)
hook_pre_compile="pwd"

hook_compile="mix compile --force --warnings-as-errors"

# A command to run right after compiling the app
hook_post_compile="pwd"

# Set the path the app is run from
runtime_path=/app

# Enable or disable additional test arguments
test_args="--cover"

The format is worth pausing on. Because the file is bash, a value can be a command substitution or an expression, which is more than a plain key and value file would give you, and it also means a stray space or an unbalanced quote breaks the build in a way that is not obvious from a stack trace.

Compile hooks are the CI and warning policy in one place

The hooks are the part of the configuration that earns its keep. There are four points where the buildpack lets you run a command, and the README describes each in turn. `hook_pre_fetch_dependencies` runs right before dependencies are fetched, `hook_pre_compile` runs right before the application is compiled, `hook_compile` is the compile step itself, and `hook_post_compile` runs after compilation. That is enough to enforce a policy. The README's own example sets `hook_compile` to `mix compile --force --warnings-as-errors`, which turns a compiler warning into a failed deploy, and it points at Heroku CI support, where adding the tapex tool makes the test runs visible on the platform. There is also `always_rebuild`, which forces a full rebuild on every deploy rather than relying on the cache, and `test_args` for extra arguments to the test run.

Pinning the buildpack itself, and using an edge version

The buildpack is a Heroku buildpack, so it is selected the way buildpacks are selected. For a new app, the command is `heroku create --buildpack hashnuke/elixir`, and for an existing app it is `heroku buildpacks:set hashnuke/elixir`. The `hashnuke/elixir` name resolves to the latest published version of the buildpack, and the README explains how to use the edge version, which is the source code in this repository, by pointing Heroku at the git URL. It also explains how to use a specific older version, by taking a commit from the commits page and appending the SHA to the URL, and it recommends doing exactly that on production applications, because it prevents the moment when a Heroku build fails because the buildpack was just updated with a breaking change. The comparison the README draws is with Hex packages pinned in `mix.lock`, which is a fair analogy for how a release should treat its own build tooling.

Elixir releases, and the warning about stacking buildpacks

The buildpack can optionally build an Elixir release, and the release build runs after `hook_post_compile`. To use it, the README gives three steps: make sure `elixir_version` in the config is at least 1.9, add `release=true` to the config, and use a Procfile line of the form `web: _build/prod/rel/foo/bin/foo start` for an app called `foo` compiled with `MIX_ENV=prod`. The feature requires the master version of the buildpack, or a commit later than 7d369c. There is a warning attached to it, and it is a good one. If you need further compilation with another buildpack, such as the Phoenix static buildpack, you probably do not want this option, and the README points at a separate buildpack for Elixir release builds instead. If your app has no Procfile at all, the buildpack falls back to running `mix run --no-halt` as the default web task.

Cloud Native, licence and a repository that still gets touched

One limitation is stated in bold in the README, and it is the one to read first. This buildpack is not guaranteed to be Cloud Native compatible, and cloud native users should use the buildpack maintained by the elixir-buildpack project, which is described as actively under development and designed specifically to follow the Cloud Native Buildpack conventions. The licence is MIT, and the repository is laid out as a buildpack, with a `bin/` directory for the executable scripts, a `lib/` directory for the shell libraries, a `test/` directory and the `elixir_buildpack.config` file that holds the defaults. The tagged releases are v1, v2 and v3, all published on 2015-10-23, with v3 described as automating Erlang builds, but the last push to the repository was on 2026-08-23, so the work continues on the default branch even though no new version has been cut for many years.

Editorial conclusion

Adopt this buildpack when a Heroku application needs a specific Elixir and Erlang pair that the default stack no longer offers, since both runtimes come from prebuilt binaries rather than a source compile. Do not adopt it if you are starting a new application on a current Heroku stack, since the README says cloud native users should use the elixir-buildpack project instead and states plainly that this buildpack is not guaranteed to be Cloud Native compatible. Verify first which Elixir and Erlang combination your application needs, because the README warns that the three variables of Erlang version, Elixir version and Heroku stack make maintenance of old combinations difficult, and pin the buildpack to a commit SHA so a deploy cannot pull a breaking change.

Frequently asked questions

Official sources

1. HashNuke/heroku-buildpack-elixir on GitHub
2. Issues
3. License: MIT
4. README
5. Releases