Adding a custom patched package with a NixOS overlay

Desired outcome

You want to use a modified version of a package (for example, a patched Emacs) in your NixOS system without altering the upstream Nixpkgs source. The overlay will make the custom package available to environment.systemPackages or service modules, and it will be built automatically during nixos-rebuild switch.

Prerequisites

• A working NixOS installation (tested on releases 22.x through 23.x; the overlay mechanism is stable across these versions).
• Root or sudo privileges to run nixos-rebuild.
• The patch file or source changes you wish to apply, accessible locally or via a URL.
• A text editor to create the overlay file (e.g., vim or nano).

Procedure

1. Create the overlay file

   Place the overlay in a location that is part of your NixOS configuration, such as /etc/nixos/overlay.nix. The file must contain a function that accepts self and super and returns a set of overrides.

   self: super:
   {
     # Example: apply a patch to Emacs
     emacs = super.emacs.overrideAttrs (old: {
       patches = old.patches ++ [
         (builtins.fetchurl {
           url = "https://example.com/my-emacs.patch";
           sha256 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab";
         })
       ];
     });
   }
   
   Replace the url and sha256 with the actual location and hash of your patch. If you prefer to use a local file, use builtins.path { path = ./my-emacs.patch; } instead of fetchurl.
   

2. Reference the overlay in configuration.nix

   Add the overlay to the nixpkgs.overlays list. This tells NixOS to evaluate your function when building the package set.

   nixpkgs.overlays = [ (import ./overlay.nix) ];
   
   If you already have other overlays, append the new one to the existing list.
   

3. Use the custom package

   Reference the patched package exactly as you would the original. For Emacs, add it to environment.systemPackages:

   environment.systemPackages = with pkgs; [ emacs ];
   
   Or, if you configure a service that depends on Emacs, ensure the service uses pkgs.emacs (which now resolves to your patched version).
   

4. Rebuild the system

   Run the rebuild command with sudo:

   sudo nixos-rebuild switch

   Nix will evaluate the overlay, fetch the patch, and build the customized Emacs.

Expected checks

• After a successful rebuild, verify that the new package appears in the Nix store:

  ls -d /nix/store/*emacs*

  You should see a directory whose name includes the hash of the patched derivation.

• Check that the package is visible to the user environment:

  nix-env -q | grep emacs

• Start the program to confirm it runs with your changes:

  emacs --version

  Look for any version strings or features you added via the patch.

• If the patched package is used by a service, inspect the service logs for warnings:

  journalctl -u emacs.service

Recovery options (rollback)

If the overlay causes a build failure or introduces unwanted behavior, you can revert by removing the overlay entry and rebuilding:

1. Edit /etc/nixos/configuration.nix and delete or comment out the line that adds the overlay:

   # nixpkgs.overlays = [ (import ./overlay.nix) ];

2. Run the rebuild command again:

   sudo nixos-rebuild switch

3. Confirm that the original, unpatched package is now in use by repeating the verification steps above.

Limitations and notes

• The overlay is evaluated at build time; any syntax error in the overlay function will prevent nixos-rebuild from completing.
• Be cautious when overriding packages that are deep dependencies of the system; unintentionally replacing a core library can break other services.
• If your patch introduces new runtime dependencies, you must add those dependencies to environment.systemPackages or the relevant service configuration.
• The example uses builtins.fetchurl to retrieve a patch from a URL; ensure the URL is accessible and the SHA‑256 hash is correct, otherwise the build will fail.