nixpkgs-wayland: pre-built Wayland packages for NixOS unstable

An overlay that tracks upstream instead of stable

nixpkgs-wayland provides automated, pre-built, potentially pre-release packages for Wayland tools in the sway and wlroots ecosystem, built for NixOS on the nixos-unstable channel. The package list in the README includes a Wayland kiosk that runs a single maximised application, a notification daemon, a small utility to dump information about DRM devices, an animated wallpaper daemon, and an OSD-style bar tool, among others.

The mechanism is a Nix overlay, and the key operational fact is in the README's opening: these packages are auto-updated to the latest version available from their upstream source control, which means the overlay and package set will often contain unreleased versions.

That sentence defines the whole project. Nixpkgs stable moves at the pace of the NixOS release cycle, which means a compositor and its ecosystem lag behind upstream git by months. This overlay exists to close that gap for the specific stack that people run on Wayland desktops.

The repository is small and has a shape you can read quickly. `overlay.nix` and `packages.nix` hold the package definitions, `pkgs/` holds the individual expressions, `flake.nix` and `flake.lock` describe the flake outputs and pin the nixpkgs revision, `default.nix` and `shell.nix` support the non-flake path, and there is a `demo/` directory with a working configuration, a legacy variant, a flake, and scripts for building and running a VM. The presence of both `main.nu` and a `flake.nix` suggests the project is being developed with flakes while still supporting the older entry points.

The maintainers are @colemickens, who started it, and @Artturin, who co-maintains it. Community chat is on Matrix at #nixpkgs-wayland:matrix.org, and the README notes they are not on Libera.

Three CI jobs that mean three different things

The continuous integration setup is the most useful part of the README for anyone deciding whether to depend on this overlay, because the three jobs are separated by what they guarantee.

The Update job tries to advance nixpkgs and upgrade all packages, and if it can successfully build them, the updates are pushed to master. So a change on master means both a newer nixpkgs base and rebuilt packages that compiled against it.

The Advance job tries to advance nixpkgs without touching the packages. The README says this can help show when an nixpkgs upgrade via nixos-unstable has advanced into a state where the project is broken building against it. In other words, this job is a canary. It does not change the packages, it changes the base, and it tells you whether the base is still compatible.

The Build job just proves that master was working against nixos-unstable at the point in time captured by whatever is in flake.lock on master. That is a statement about a specific captured state rather than about the current state of the unstable channel, which is the difference that matters for anyone pinning.

The separation is deliberate and it is a good design. Advancing the base and upgrading the packages are coupled in a way that makes failures ambiguous: did the new upstream release break, or did nixpkgs move? Splitting them means each job's result is interpretable.

One caveat is stated plainly: there is no CI on pull requests, and the maintainer keeps an eye on it after merging external contributions. So an outside contribution is not automatically verified by the same gates that protect master, and the first build of it happens on the branch that was merged.

The binary cache is what makes it usable

Building a compositor and its tools from source on your own machine is not what anybody wants, so the binary cache is the feature that turns this overlay from a curiosity into something usable.

The README says packages from this overlay are regularly built against nixos-unstable and pushed to this cache, and points at the Cachix landing page for nixpkgs-wayland for the details of how to use it. The cache is where the build products go, and your machine downloads them instead of compiling them.

For a flake user, the wiring is a substituter plus a trusted key. The README's example configuration lists both the standard NixOS cache and the nixpkgs-wayland one:

              trusted-public-keys = [
                "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
                "nixpkgs-wayland.cachix.org-1:3lwxaILxMRkVhehr5StQprHdEo4IrE8sRho9R9HOLYA="
              ];
              substituters = [
                "https://cache.nixos.org"
                "https://nixpkgs-wayland.cachix.org"
              ];

The key is the security-relevant part. A substituter is a place your system fetches binaries from, and adding a trusted public key tells Nix to accept the signatures on the store paths that substituter publishes. You are extending the set of parties whose content you trust to the maintainers of this overlay, and the key in the README is what makes that explicit and reviewable.

The same example shows the two ways to consume the overlay. It can be used as an overlay through `nixpkgs.overlays = [ inputs.nixpkgs-wayland.overlay ]`, or you can pull specific packages built against the overlay's own nixpkgs, which the README says is usually nixos-unstable:

That distinction is a real one. Overlay usage means the package is rebuilt against your own nixpkgs pin, so it fits your configuration. Pulling the package set means you get the overlay's build, which is pinned to its own nixpkgs and may not line up with your system.

Running a package without writing a configuration

The quickest way in is the one-line shell example the README gives for trying a single tool.

For OBS-Studio, the Wayland-fixed up version referenced in the pull request:

  nix shell "github:nix-community/nixpkgs-wayland#obs-studio" --command obs

And for wev, the Wayland debugger:

  nix run "github:nix-community/nixpkgs-wayland#wev"

These two commands are the fastest possible evaluation of the overlay, and they need no configuration, no channel and no overlay wiring. `nix run` fetches the flake, resolves the package, downloads it from the binary cache if it is there, and executes it. If the binary is not in the cache, it builds locally, which is the slow path and the reason the cache matters.

The README also documents the non-flakes path for NixOS, and points at the NixOS wiki page on overlays for the general case. The literal example fetches the overlay as a tarball with a rev you choose, imports its overlay.nix, and adds it to nixpkgs.overlays:

    nixpkgs.overlays = [ waylandOverlay ];
    environment.systemPackages = with pkgs; [ wayvnc ];

In that example the rev line carries a comment saying it could be a git rev, to pin the overlay, and that part matters for anyone who cares about reproducibility. The README says if you do pin, use a tool like `niv` to do the pinning so that you don't forget and wind up stuck on an old version. That is an admission that master tracking is the default and that untracked pinning is a trap.

For non-NixOS users, the README offers two routes: activate flakes mode and run the one-line examples outright, or add the overlay at the user level in `~/.config/nixpkgs/overlays.nix` or a file under `~/.config/nixpkgs/overlays/`, then install packages with `nix-env`:

nix-env -iA neatvnc

The user-level route does not pin the overlay, and the README says so directly.

Where a moving package set hurts

The main cost of this project is the one the README states outright: the package set often contains unreleased versions, and master moves whenever the Update job succeeds.

For a workstation where you want the newest compositor, that is a feature. For anything you rebuild from a lockfile expecting the same result, it is a hazard. The distinction matters in CI, in a container image, and in a configuration management system, where a build that worked last month may resolve different sources today.

The mitigation is available and the README points at it. The flake.lock captures the nixpkgs revision, and the Build job's promise is precisely that master built successfully against the nixos-unstable state captured in that lockfile. So a team that commits flake.lock and rebuilds from it gets a defined base, and a team that tracks master gets a moving one. The trap is in between, where someone tracks the branch without committing the lock, and gets updates they did not ask for.

There is a second limitation worth naming. This is an overlay over nixpkgs, so it inherits nixpkgs' own packaging decisions and inherits its churn. The Update job advances nixpkgs as well as the packages, which means the base moves twice as fast as a stable channel would, and the Advance job exists precisely because that base sometimes reaches a state where the packages do not build. The canary reduces the surprise, but it does not remove the coupling.

A third point is about coverage. The package list in the README is a curated set of sway and wlroots ecosystem tools, not the whole Wayland desktop. A tool the overlay does not carry falls back to whatever nixpkgs has, which for a recent release of an upstream project may be nothing at all. The overlay is a way to get the listed packages faster, not a complete Wayland environment.

Finally, the licence is not stated. No licence is stated for nixpkgs-wayland, and the top level does not list a LICENSE file, so anyone redistributing the built packages has to work that out from nixpkgs' own terms rather than from this repository.

How this differs from tracking upstream in your own configuration

There are two realistic alternatives, and the difference in approach is instructive.

The first is to define the packages yourself. In a nixpkgs overlay of your own, you pin a specific upstream tag or commit for each tool, write the derivation yourself, and rebuild when you choose. The result is a package set you fully control, at the cost of doing the work the overlay already does: tracking releases, writing and updating the build expressions, and keeping the derivation working as upstream changes.

The second is to use a different channel. The nixos-unstable channel itself is already upstream-tracking for a large part of the ecosystem, and it is the base this overlay is built on. If the tool you need is packaged in nixpkgs unstable, using unstable directly is fewer moving parts, at the cost of the same churn applied to your whole system rather than to a curated set.

The overlay's contribution is the third path. It narrows the instability to a specific set of packages, it builds them for you so you do not compile a compositor on your laptop, and it publishes to a cache so the binaries are already there. The trade is that you are trusting a community overlay's judgment about what to package and how to build it, and the trust extends to the binary cache key you add to your configuration.

For a user, the practical decision is narrow. If the tool you need is on the package list and nixpkgs stable is too old, the overlay is the cheapest path. If it is not on the list, the overlay does not help and the comparison above is the one to make.

Editorial conclusion

Adopt nixpkgs-wayland when you are on NixOS and need a recent sway or wlroots tool that nixpkgs stable does not carry yet, and when you are prepared to let the package set move under you, since the README states the overlay often contains unreleased versions. Do not adopt it for a reproducible production deployment, where an unattended nixpkgs advance can change what your machine contains. Before you switch, read the three CI job descriptions to understand what an update, an advance and a build each guarantee, add the nixpkgs-wayland substituter and its trusted key, and pin a revision rather than tracking master if you need a stable base.

Frequently asked questions

Official sources

1. Issues
2. nix-community/nixpkgs-wayland on GitHub
3. README