Library / SDK
rusterlium/rustler avatar
rusterlium/rustler

Rustler: writing BEAM NIFs in Rust, with the panic boundary spelled out

Safe Rust bridge for creating Erlang NIF functions

4,898 stars250 forksRustApache-2.0

At a glance

What is it?
Rustler is an Apache-2.0 or MIT library that lets Erlang and Elixir projects load Rust code as NIFs, generating the module boilerplate and catching Rust panics before they unwind into C. Elixir is the favored path, and a few decisions, from the default NIF version of 2.17 to the 1.91 minimum Rust version, are worth checking before you commit.
Who is it for?
Rustler fits teams that already run Elixir or Erlang and want hot native code without hand-written C glue, provided they accept the Elixir-first workflow and pin their toolchain to Rust 1.91 or newer. Before you build on it, confirm which OTP release your production nodes run, since the default NIF version is 2.17 and 2.18 needs an explicit feature flag.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 5 days ago.
What is it written in?
Mainly Rust, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • rusterlium/rustler4,898 ★ · +34
Star history
Repository2026-09-232026-11-21
rusterlium/rustler4.9k4.9k

34 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The panic boundary stops at the NIF, not at the scheduler

Rustler's safety claim is specific: code you write in a Rust NIF should never be able to crash the BEAM, and the library catches Rust panics before they unwind into C. That is a narrower guarantee than it sounds. It is not a mechanism for making a slow function fast, and nothing in the project's documentation describes how Rustler handles a NIF that blocks the scheduler thread for a long time or how to mark work as dirty. If your native function does real computation over a large data set, the safety net will catch a panic and hand you a clean error, but it will not hand you back the scheduler. Treat Rustler as a bridge for short, bounded operations and check your own runtime behavior on the BEAM side before you rely on it in a request path.

Term encoding is a function call, struct mapping is one attribute

The interop story rests on two claims. First, decoding and encoding Rust values into Erlang terms is as easy as a function call, which is what the minimal example shows:

rust
#[rustler::nif]
fn add(a: i64, b: i64) -> i64 {
    a + b
}

rustler::init!("Elixir.Math");

Second, making a Rust struct encodable and decodable to Erlang or Elixir can be done with a single attribute. Note what that example does not contain: there is no manual term construction, no length parsing, no NIF entry stub, and no unload callback. The attribute on the function and the `rustler::init!` string naming `Elixir.Math` are the whole registration. The cost of that convenience shows up in the module name. Because the Elixir module is named in the macro, renaming `Math` means editing the Rust source and recompiling the shared object; there is no runtime lookup that would tolerate a mismatch between the module you registered and the module that calls `add`.

Resource objects are dropped when the last Erlang reference goes

The resource mechanism lets you pass a reference to a Rust struct into Erlang code, and the struct is dropped automatically when it is no longer referenced. That is the piece that makes it safe to hold native memory behind an Erlang term instead of leaking it. The practical consequence is about lifetimes on the BEAM side: a resource term keeps the Rust allocation alive as long as any process, message, or ETS entry still points at it, so a long-lived process that stashes a resource in its state pins the native memory for the life of that process. Garbage collecting the BEAM does not collect it early. The project's own test workspace reflects how much of this surface matters: `rustler_tests/native/` contains separate crates for `resource_dyncall`, `rustler_serde_test`, `rustler_bigint_test`, `dynamic_load`, `binary_example`, and `rustler_compile_tests`, which is a fair hint about where the sharp edges are.

The default NIF version and feature flags

The supported NIF version is a Cargo feature, and the default is 2.17, which corresponds to Erlang/OTP 26. Features from NIF version 2.18 (Erlang/OTP 29) have to be switched on by hand:

toml
[dependencies]
rustler = { version = "...", features = ["nif_version_2_18"] }

This is the setting most likely to surprise you. If you run your application on OTP 29 and expect the newer NIF version, you get 2.17 unless you name the feature. Separately, Rustler aims to support the newest three major OTP versions along with the newest three minor Elixir versions, so a fleet pinned to something older than that window is outside the stated support range even when the crate still compiles.

The mix task is the documented path, and serde users must re-opt in

The documented entry point is Elixir: add the rustler Elixir library from Hex as a dependency, run `mix rustler.new`, and follow the instructions it prints. If you already use `serde` or have used `serde_rustler`, you also need to enable the `serde` feature on the rustler dependency in your NIF crate's `Cargo.toml`. That second step is the trap in the quick start. A team migrating from `serde_rustler` to rustler has a working mental model of derive-based conversion, and a silent default feature set means the derives you expect are not compiled in until you add the flag yourself. The crate does work for plain Erlang projects too, but the README is explicit that Elixir is favored as of now, and the generator task lives in the Elixir wrapper rather than in the Rust crate.

A pnpm-sized workspace with default members that build alone

The repository is a Cargo workspace with `resolver = "2"` and eleven members, including the `rustler` crate, `rustler_codegen`, the `rustler/otp_headers/codegen` package, a benchmarks crate, and seven test crates under `rustler_tests/native/`. `default-members` lists only `rustler` and `rustler_codegen`, which means a plain `cargo build` at the root skips the tests, the benchmarks, and the header generator. The repository's `justfile` encodes the fuller loop: `build` runs `cargo build` and then `cd rustler_mix && mix deps.get && mix compile`, while `test` runs `cargo test -q` followed by `mix deps.get && mix test` in both `rustler_mix` and `rustler_tests`. That split is the point worth remembering. Verification crosses the language boundary, and a green `cargo build` tells you nothing about whether the Elixir side compiles or the native test crates pass.

MSRV 1.91 lives in .clippy.toml, so toolchain drift shows up at lint time

Rustler declares a minimum supported Rust version of 1.91, and the interesting detail is where that number lives: it is the configured version in `.clippy.toml`. For a downstream team this matters twice, once for your own CI and once for anyone building from source, because the same floor applies to both. The repository also carries a `prepare_release.sh` script and a `RELEASE_CHECKLIST.md` next to an `UPGRADE.md` and a `CHANGELOG.md`, and the recent tags show the cadence: 0.37.4 on 2 May 2026, 0.38.0 on 25 May 2026, and 0.39.0 on 12 October 2026, with the last push to master on 23 October 2026. Read `UPGRADE.md` before jumping a minor version rather than assuming a semver-compatible upgrade is free.

Editorial conclusion

Rustler fits teams that already run Elixir or Erlang and want hot native code without hand-written C glue, provided they accept the Elixir-first workflow and pin their toolchain to Rust 1.91 or newer. Before you build on it, confirm which OTP release your production nodes run, since the default NIF version is 2.17 and 2.18 needs an explicit feature flag.

Frequently asked questions

What does Rustler actually do for an Elixir project?

It lets you write NIF functions in Rust and load them from Erlang or Elixir, generating the boilerplate for talking to the BEAM, handling the encoding and decoding of Erlang terms, and catching Rust panics before they unwind into C.

Is Rustler safe for the Erlang VM?

Rustler states that code you write in a Rust NIF should never be able to crash the BEAM, because it catches Rust panics before they unwind into C. The guarantee is scoped to panics crossing that boundary, not to the runtime cost of the function you call.

How do I start a new NIF project with Rustler?

Add the rustler Elixir library from Hex as a dependency of your project, then run `mix rustler.new` and follow the instructions. If you already use `serde` or have used `serde_rustler`, enable the `serde` feature on the rustler dependency in your NIF crate's `Cargo.toml`.

Which OTP versions does Rustler support?

Rustler aims to support the newest three major OTP versions as well as the newest three minor Elixir versions. The default minimal supported NIF version is 2.17, which corresponds to Erlang/OTP 26, so features from 2.18 (Erlang/OTP 29) have to be enabled as a Cargo feature on the dependency.

What is the minimum Rust version Rustler needs?

The minimum supported Rust version is 1.91, and that value is the configured version in `.clippy.toml`.

How is Rustler licensed?

Rustler is licensed under either the Apache License, Version 2.0 or the MIT license, at your option. Unless a contribution states otherwise, it is dual licensed the same way with no additional terms.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. rusterlium/rustler on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/rusterlium-rustler.svg)](https://hysenlabs.com/projects/rusterlium-rustler)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/rusterlium-rustler.svg)](https://hysenlabs.com/projects/rusterlium-rustler)

Was this useful?