Fixing Packages with Overlays

Fixing Packages with Overlays

Thesis

A Nix overlay is a function (final: prev: { … }) that patches the package set: bump a version, swap a dependency, apply a local fix — without forking all of nixpkgs. Overlays compose; later overlays see earlier results via final.

Mental model

  prev  = package set so far
  final = package set after all overlays (fixed point)

  overlays = [
    (final: prev: { hello = prev.hello.overrideAttrs (...); })
  ]

Prefer final when referring to packages that might themselves be overlaid; prefer prev for the pre-overlay package you are replacing.

Worked example

Docs-based flake fragment (nix not on this box):

# overlays/default.nix
final: prev: {
  mycurl = prev.curl.overrideAttrs (old: {
    configureFlags = (old.configureFlags or []) ++ [ "--disable-ares" ];
  });
}

# flake.nix (excerpt)
{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
  outputs = { nixpkgs, ... }: {
    packages.x86_64-linux.default =
      let
        pkgs = import nixpkgs {
          system = "x86_64-linux";
          overlays = [ (import ./overlays) ];
        };
      in pkgs.mycurl;
  };
}

On a Nix host: nix build .#default and nix why-depends to confirm the override.

Trap

Infinite recursion — referencing final.hello inside the overlay that defines hello without going through prev, or cycles across overlays. Also: overlays that silently rename packages break dependents expecting upstream attribute names.

Boring rule

Keep overlays small, named, and version-controlled next to the flake. Prefer overrideAttrs / override over copying whole package expressions. Drop the overlay once nixpkgs absorbs the fix.

Try this

1. Overlay a package to add a patches = [ ./fix.patch ];.
2. Compose two overlays and predict final vs prev for a shared dependency.
3. Compare overlays with pkgs.extend and NixOS nixpkgs.overlays.

Sources

• Nixpkgs manual: Overlays
• NixOS manual: nixpkgs.overlays
• nix.dev tutorials on overlays