# The emacs overlay tracks master daily, and that is its bargain

> emacs-overlay is a Nixpkgs overlay that packages Emacs from git, ELPA and MELPA archives, and EXWM, regenerated daily. It gives Nix users bleeding edge Emacs at the cost of rebuilds and instability the README states plainly.

**nix-community/emacs-overlay** — Bleeding edge emacs overlay [maintainer=@adisbladis] 

- Repository: https://github.com/nix-community/emacs-overlay
- Stars: 643 · Forks: 185
- Language: Nix
- License: not declared
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nix-community-emacs-overlay

## An overlay for Nixpkgs, not a way to build Emacs

emacs-overlay lives in the nix-community organisation and is described in the repository as a bleeding edge Emacs overlay. The primary language is Nix and the top level of the tree is a small set of Nix files plus generated data directories.

The mechanism is Nix overlays rather than a build system of its own. The README calls the project an overlay for Nixpkgs, and the quickstart is a snippet you paste into your NixOS configuration to register the overlay and then point your system wide Emacs at one of the attributes it defines. The overlay does not build Emacs from scratch in some alternative way. It wraps the existing Nixpkgs machinery and supplies newer inputs.

That framing determines who the audience is. If you are not already using Nix or NixOS, there is nothing here for you, because every instruction assumes the Nix expression language and the Nixpkgs overlay concept. The README even points readers to the Nixpkgs and NixOS documentation on package overlays and overrides before continuing, which tells you the overlay is treated as a normal Nixpkgs citizen rather than a standalone tool.

For the Nix user, the value proposition is precise: the version of Emacs in Nixpkgs is a release, and this overlay gives you the git build, the daily package archives and a window manager, all expressed as Nix attributes you can pin like anything else in your configuration.

## Two overlays in one: package and emacs

The README states that the overlay consists of two overlays, named emacs and package, and that you can use both as a whole overlay or only one of them. Splitting them is a small decision with real consequences, because the two halves have very different stability profiles.

The package overlay is about archives. It provides daily generations of Elpa, and daily generations of Melpa and Melpa stable attribute sets. It also provides fresh versions of EXWM and the dependencies it needs, updated daily. In other words, this half is about the ecosystem around Emacs rather than Emacs itself: the package archives and one window manager, all refreshed on a daily cycle.

The emacs overlay is about the editor binary. It provides two versions built from git, updated daily, named emacs-git and emacs-unstable. The README is precise about the difference between them, and it matters for reproducibility: emacs-git is built from the latest master branch, while emacs-unstable is built from the latest tag.

That single distinction is the reason to use one rather than the other. A tag is a fixed point that upstream chose, so emacs-unstable changes when upstream cuts a new one. master moves continuously, so emacs-git can change on any given day, and the README warns that Emacs from git is not guaranteed stable and may break your setup at any time.

For a Nix user, being able to choose between the two per attribute is a useful degree of freedom, and the split also lets you take only the package archives without taking a git Emacs.

## The nox and pgtk variants decide your window system

Beyond the two base attributes, the README lists four more, and they are about the windowing stack rather than about Emacs features.

The nox variants, emacs-git-nox and emacs-unstable-nox, are for people who want Emacs built without X dependencies. That is the variant for a headless setup, a terminal-only workflow, or a machine where pulling in the X stack is not wanted.

The pgtk variants, emacs-git-pgtk and emacs-unstable-pgtk, enable the pure GTK feature, which the README describes as incompatible with X and supporting Wayland natively. So the four extra attributes reduce to two binary choices, nox or with X, and PGTK or not, crossed with git or tag based.

The PGTK choice is the one that will decide for a Wayland user, and it is also the one that can lock you out of X11 applications, since the README states the incompatibility plainly rather than hinting at it. If your desktop is X11, the default attributes are the safe ones. If it is Wayland, PGTK is what you want and you should be deliberate about it.

The README does not describe a native Wayland build without GTK, so PGTK appears to be the path for Wayland in this overlay.

## Wiring the overlay into a NixOS configuration

The quickstart in the README is short enough to quote in full, and it shows exactly how the overlay is meant to be consumed.

```nix
{config, pkgs, callPackage, ... }:
{
  services.emacs.package = pkgs.emacs-unstable;

  nixpkgs.overlays = [
    (import (builtins.fetchTarball {
      url = "https://github.com/nix-community/emacs-overlay/archive/master.tar.gz";
    }))
  ];
}
```

Two settings do the work. The overlay is imported from a tarball fetched at evaluation time, and the system wide Emacs package is set to pkgs.emacs-unstable, which the README explains is the attribute the overlay provides.

The README is also blunt about the risk of that exact snippet. It notes the configuration has the potential to break things and will frequently trigger full source rebuilds of Emacs. That is the cost of pointing at master, and it is not a bug in the configuration.

If you want the server mode, the daemon that keeps a session running so the client starts instantly, the README gives one more line for the same file.

```nix
services.emacs.enable = true;
```

## emacsWithPackagesFromUsePackage reads your own config

The most interesting part of the overlay is a layer of helper functions on top of the standard emacsWithPackages. The README says the overlay comes with extra functions to generate an Emacs closure from various types of dependency declaration, and calls them abstractions on top of emacsWithPackages.

emacsWithPackagesFromUsePackage does the thing that most Emacs users want and that Nix has traditionally made awkward: it adds the packages your config requires. Point it at your .el file, and it parses the file and pulls in what use-package or leaf declares. The README example shows the shape, with a config path, a package attribute, and switches for ensure and tangle behaviour.

The switches have warnings attached, and those warnings are the interesting part. By default only packages with an ensure declaration are pulled in. Setting alwaysEnsure to true emulates use-package-always-ensure and pulls in every reference not explicitly disabled, and the README says this is not recommended unless you have actually set use-package-always-ensure to t. The same pattern applies to alwaysTangle for Org mode babel files, where code blocks without a tangle argument are included by default.

That is careful engineering in the documentation: the helper matches the semantics of the Emacs packages it mirrors, and it tells you when turning a flag on will change behaviour relative to Emacs itself. There is also an extraEmacsPackages list for anything you want to add by hand, including executables such as linters and language servers, and an override hook for patching individual derivations.

## Package-Requires as a dependency source for CI

The second helper is emacsWithPackagesFromPackageRequires, which adds packages declared in a .el file's Package-Requires header rather than in a user config. The README suggests this is handy for CI purposes, and the example builds a shell derivation with the resulting Emacs in its buildInputs.

```nix
let
  emacsForCI = pkgs.emacsWithPackagesFromPackageRequires {
    packageElisp = builtins.readFile ./flycheck.el;
    extraEmacsPackages = epkgs: [
      epkgs.package-lint
    ];
  };
pkgs.mkShell {
  buildInputs = [ emacsForCI ];
}
```

The distinction matters in a specific way. A user config is a moving target that pulls in whatever the author felt like using, while a package header is a declaration a package author has committed to. For continuous integration, deriving the dependency set from package headers gives you the dependencies of the packages you are testing rather than the preferences of a person, which is exactly the kind of drift you want to avoid in a build.

The example reads the .el file with builtins.readFile and adds package-lint on top, so the CI shell gets both the package's declared dependencies and a linter. Note that the helper takes file contents, not a path, which is how Nix expressions normally consume files.

## Master tarball versus a pinned revision, and the binary cache

The overlay is distributed in two ways, and the difference between them is the single most consequential choice you make.

The quickstart fetches the master tarball at every rebuild. The README calls this the most convenient way to pull in the overlay, and then describes the side effects: packages may break, and you may want to be in control of which revision of the overlay you run. Adding the overlay this way extends your Emacs package set with the latest EXWM and dependencies from their master branches and makes emacs-git available, and since those change rapidly they cause compilation time.

The README then gives the same overlay expression with only the nixpkgs.overlays block, without touching services.emacs.package, which is the form you would use once you want to select an attribute yourself.

There is a third practical ingredient. The README says you will want to use the nix-community binary cache, where the overlay's build artefacts are pushed, with installation instructions linked from the nix-community site. That is what makes daily rebuilds tolerable, because the artefacts are already built on the cache rather than on your machine.

The repository layout supports the daily cycle. There is an update script at the top level, a repos/ directory, a default.nix, elisp.nix for the package archive generation, parse.nix, packreq.nix for the Package-Requires helper, an overlays/ directory, and a flake.nix with flake.lock for the flake interface.

## Licence, stability and the honest cost of bleeding edge

Start with the stability warning, because the README is unusually direct about it: Emacs from git is not guaranteed stable and may break your setup at any time, and if it breaks you get to keep both pieces. Add the note that the quickstart configuration will frequently trigger full source rebuilds of Emacs, and you have the real trade-off of this project stated in the project's own words.

This is the wrong tool in several situations. If you want a reproducible system configuration, fetching master on every rebuild means your system changes without a commit, and if you pin to master instead you are pinning to a moving target. If you need a long lived server with a stable Emacs, the daily rebuild churn is a liability rather than a feature. And if you cannot rebuild Emacs from source in your environment, the overlay does not help you, since the point is to build from git in the first place.

The licence is the other soft spot. The repository records no licence for this project, and the top level entries include README.org, default.nix, the overlays and the update script but no LICENSE file. For most people who consume a public overlay that is not a practical problem, since nothing here is being redistributed. For a team that vendors the overlay into an internal configuration repository, the absence of a recorded licence is a question worth asking upstream.

On maintenance, the repository is not archived and the last push was on 2026-10-20. There are no GitHub releases, so there is no version to pin to other than a commit or the flake lock, which is why the tarball approach and the pinned revision approach are both described in terms of the tarball URL.

## Conclusion

Adopt emacs-overlay if you are already on Nix or NixOS and want an Emacs built from a recent git commit with MELPA packages generated daily, and you can accept rebuild churn. Do not adopt it if you want a stable package, if you cannot tolerate rebuilds triggered by upstream commits, or if you need a licence you can name, since the repository does not record one. Before you wire it into /etc/nixos/configuration.nix, pin the overlay to a specific revision rather than the master tarball, add the nix-community binary cache, and check that the emacs-unstable attribute tracks the latest tag while emacs-git tracks master.

## FAQ

### How do I add emacs-overlay to my NixOS configuration?

The README shows adding nixpkgs.overlays with an import of a fetched tarball of the repository, and setting services.emacs.package to pkgs.emacs-unstable. It also notes the configuration has the potential to break things and will frequently trigger full source rebuilds of Emacs.

### What is the difference between emacs-git and emacs-unstable?

emacs-git is built from the latest master branch and emacs-unstable is built from the latest tag. Both are updated daily, and the README warns that Emacs from git is not guaranteed stable and may break your setup at any time.

### What do the nox and pgtk Emacs attributes do?

emacs-git-nox and emacs-unstable-nox are built without X dependencies, while emacs-git-pgtk and emacs-unstable-pgtk enable the pure GTK feature, which the README says is incompatible with X and supports Wayland natively.

### How does emacsWithPackagesFromUsePackage work?

It generates an Emacs closure that includes the packages required in a user's config through use-package or leaf, and it can include Org mode babel files. By default it only pulls in packages with an ensure declaration, and the README says setting alwaysEnsure to true is not recommended unless use-package-always-ensure is set in the config.

### What does emacs-overlay provide besides Emacs itself?

The package overlay provides daily generations of Elpa and of Melpa and Melpa stable attribute sets, plus fresh versions of EXWM and its dependencies, also updated daily. The project recommends using the nix-community binary cache for the build artefacts.

## Sources

- [Issues](https://github.com/nix-community/emacs-overlay/issues)
- [nix-community/emacs-overlay on GitHub](https://github.com/nix-community/emacs-overlay)
- [README](https://github.com/nix-community/emacs-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/nix-community-emacs-overlay