# oxalica/rust-overlay: reproducible Rust toolchains in Nix

> oxalica/rust-overlay is a Nix overlay and Flake interface for installing binary Rust toolchains with pre-fetched hashes. It is aimed at Nix users who need stable, beta, nightly, versioned, or cross-compiled Rust environments, with nightly selection requiring extra care.

**oxalica/rust-overlay** — Pure and reproducible nix overlay of binary distributed rust toolchains

- Repository: https://github.com/oxalica/rust-overlay
- Stars: 1,572 · Forks: 86
- Language: Nix
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/oxalica-rust-overlay

## Why rust-overlay exists for Nix Rust development

oxalica/rust-overlay solves a packaging problem specific to Nix users: making binary-distributed Rust toolchains available as reproducible Nix packages. Rust is normally obtained through tools such as rustup, while Nix evaluates package definitions and records the inputs needed to construct an environment. The overlay bridges those models by describing official Rust components and their fixed hashes as Nix attributes.

The repository presents itself as a compatible replacement for the rust overlay in nixpkgs-mozilla. Its intended users are developers who already work with NixOS, Nix shells, nixpkgs, or Nix Flakes and want Rust toolchain versions exposed through package attributes. The package paths distinguish stable, beta, and nightly channels, with selectors for the latest release and named versions such as stable 1.48.0 or nightly 2020-12-31.

This is not a compiler implementation or a replacement for rustup. It packages binary toolchains supplied by the Rust distribution channel. That distinction matters for adoption. A team seeking reproducible development environments can use the overlay to keep Rust packages in a Nix configuration. A user who only needs a personal rustup installation may not gain enough from the additional packaging layer.

## Pure evaluation and automatic hash maintenance

The main design choice is the pre-fetching of toolchain component hashes in the repository tree. According to the README, this makes evaluation pure and means that network access is not needed during evaluation. The resulting package definitions can be evaluated in environments that are expected to remain independent of the live Rust download infrastructure.

The repository also documents daily hash updates through GitHub Actions. This automation matters because binary Rust components can change over time, and a fixed source URL is not enough for a reproducible Nix package if the content behind it changes. Keeping hashes in the repository turns that changing distribution problem into a repository update problem. The README says stable versions are not currently purged, while older nightly versions are handled through snapshot tags.

That history policy has a practical cost. Stable versions remain available in the normal tree, but nightly versions before the current retention boundary may not be directly available there. The README states that the current oldest supported nightly is 2025-01-01 and that nightly and beta versions earlier than the current year minus one may require old snapshot tags. Nightly users therefore need to decide whether their selected date is still present in the main repository before designing a long-lived build.

## Stable, beta, nightly, and versioned package selection

The `rust-bin` interface provides the main package paths. A stable default profile is available at `rust-bin.stable.latest.default`, while a minimal profile is available at `rust-bin.stable.latest.minimal`. The README says these correspond to the components installed by the `rustup install` default and minimal profiles. A beta toolchain follows the same structure through `rust-bin.beta.latest.default` and `rust-bin.beta.latest.minimal`.

Extra components and target support are added with `override`. The documented expression adds `rust-src` as an extension and `arm-unknown-linux-gnueabihf` as a target. This mechanism is useful when a project needs a component that is not part of the selected profile, such as Rust source files or platform libraries.

Named versions use channel-specific attributes, including `rust-bin.stable."1.48.0".default` and `rust-bin.nightly."2020-12-31".default`. Nightly selection has one important restriction. The README explicitly warns against `rust-bin.nightly.latest`, because a build can fail when required components are missing on a particular day. It recommends `rust-bin.selectLatestNightlyWith`, which lets the caller choose a toolchain and then apply the normal profile or overrides:

```nix
rust-bin.selectLatestNightlyWith (toolchain: toolchain.default)
```

This selector shifts nightly usage away from an unconstrained latest attribute and toward an expression that can account for profile and component requirements. It does not make nightly builds reproducible by itself. Reproducibility still depends on selecting a version and having all required component hashes available.

## Installation paths for overlays and Flakes

The classic installation method registers the repository as a Nix overlay. The README places this expression in `~/.config/nixpkgs/overlays.nix`:

```nix
[ (import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz")) ]
```

After the overlay is registered, the documented installation command selects the latest stable default toolchain. The `nixpkgs` name in the path represents the reader's Nix channel name, and the README notes that `nixos` can serve that role.

```bash
$ nix-env -iA nixpkgs.rust-bin.stable.latest.default
```

The repository also documents channel installation. This adds the archive as the `rust-overlay` channel and updates the channel list:

```bash
$ nix-channel --add https://github.com/oxalica/rust-overlay/archive/master.tar.gz rust-overlay
$ nix-channel --update
```

With the channel available, the README shows importing `<nixpkgs>` and applying `<rust-overlay>` through its `overlays` argument. For a first real use through Flakes, the README gives a direct command:

```bash
$ nix shell github:oxalica/rust-overlay
$ rustc --version
$ cargo --version
```

The command brings a Rust toolchain into scope. The version printed by `rustc` is not fixed by the README example, so a newer version can legitimately appear. The README also warns that only the `overlay` and `overlays` Flake outputs are currently stable. Other outputs should not be treated as a stable interface.

## Embedding the overlay in NixOS and devShell configurations

For NixOS, the documented Flake pattern declares `nixpkgs` and `rust-overlay` as inputs, makes `rust-overlay` follow the `nixpkgs` input, applies `rust-overlay.overlays.default`, and adds `pkgs.rust-bin.stable.latest.default` to `environment.systemPackages`. The example uses `x86_64-linux`, which is the platform named in the README's support statement.

A development shell uses a similar overlay import but selects the beta default toolchain. The example also includes `openssl`, `pkg-config`, `eza`, and `fd`, showing that the Rust package is composed with ordinary shell dependencies rather than replacing the whole development environment. The shell then defines aliases through `shellHook`.

This interface is useful when a repository's toolchain selection should be declared as part of its flake inputs. It also makes the selected profile visible in configuration. The boundary is equally important. The README says the project targets `nixos-unstable` and supported NixOS releases on `x86_64-linux`, with other platforms and nixpkgs channels possibly working but not guaranteed. A macOS or ARM configuration should not treat the same expression as a documented, tested path. The repository includes cross-compilation examples such as `examples/cross-aarch64/`, `examples/cross-mingw/`, and `examples/cross-wasi/`, but their presence does not by itself guarantee native support for those platforms.

## Cross compilation, upgrades, and repository boundaries

The repository has dedicated cross-compilation documentation and example directories, so cross compilation is part of the intended scope rather than an incidental mention. The README links `docs/cross_compilation.md` and describes the `rust-bin` interface as having Nix-aware cross-compilation support. Its component model allows a caller to request additional targets with `override`, which is relevant when a Nix build needs a target library or cross-compiled standard library.

Cross compilation and native platform support should not be conflated. A project can expose a target through its toolchain definition while still operating in a package set that is not documented as tested for the host platform. The README's explicit test target is `x86_64-linux`; unsupported combinations need to be checked against the linked documentation and the examples.

Upgrade cost comes from two directions. First, the project is a packaging layer over upstream Rust distributions, so changes to component availability, profiles, targets, or hashes can require reviewing the overlay. Second, the repository's Flake warning limits confidence in outputs other than `overlay` and `overlays`. A team adopting a non-overlay output takes on an interface the README explicitly labels unstable.

The repository has no GitHub releases, so release notes are not available as an upgrade source. Maintenance status can only be stated from repository metadata: it is not archived, and the last push was on 2026-10-15. The MIT license permits use and modification under its terms, but this article does not interpret those terms as legal advice.

## Where rust-overlay is the wrong choice

rust-overlay is a poor fit when the requirement is a globally managed Rust installation with rustup behavior rather than a Nix package. It is also a poor fit for a host platform that is not documented and tested, especially outside `x86_64-linux`. The README says other platforms and nixpkgs channels may work, but it does not guarantee them.

Nightly automation introduces another failure mode. The README warns that `rust-bin.nightly.latest` can fail if components are missing on a given day. `selectLatestNightlyWith` is the documented selector, but callers still need to decide which components and targets their build requires. A project that requires a very old nightly may also need an old snapshot tag because the main repository retains a bounded nightly history.

The Flake boundary is a practical reason to stop and reconsider if a build depends on an output beyond `overlay` or `overlays`. The README calls those other outputs unstable. Teams that need a guaranteed interface should first check whether the stable output set covers their configuration. If it does not, adopting the project may mean accepting an upstream interface that can change without a GitHub release.

## Conclusion

Adopt oxalica/rust-overlay when a Nix project needs reproducible Rust packages and can accept its supported-platform and Flake-output boundaries. Do not adopt it as a general Rust distribution system without checking x86_64-linux support, the stability of non-overlay Flake outputs, and the availability of required nightly components first. The repository was last pushed on 2026-10-15 and has an MIT license.

## FAQ

### How do I install oxalica/rust-overlay as a classic Nix overlay?

Add the documented `builtins.fetchTarball` expression to `~/.config/nixpkgs/overlays.nix`. The repository also documents adding its archive as a Nix channel with `nix-channel`.

### Which oxalica/rust-overlay package should I choose for normal Rust development?

The README says to use `rust-bin.stable.latest.default` when unsure. It describes this as the stable default profile and contrasts it with `minimal`, which excludes components such as rustfmt and clippy.

### Can I use oxalica/rust-overlay with Nix Flakes?

Yes. The README provides `nix shell github:oxalica/rust-overlay`, a NixOS configuration example, and a `devShell` example. It warns that only the `overlay` and `overlays` outputs are currently stable.

## Sources

- [Issues](https://github.com/oxalica/rust-overlay/issues)
- [License: MIT](https://github.com/oxalica/rust-overlay/blob/master/LICENSE)
- [oxalica/rust-overlay on GitHub](https://github.com/oxalica/rust-overlay)
- [README](https://github.com/oxalica/rust-overlay/blob/master/README.md)

---

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