Overlays, override, and overrideAttrs

️ What are Overlays?#

Overlays are a core Nixpkgs mechanism. Think of them as a layer of your own definitions applied over the official pkgs.

1. Basic syntax

self: super: {
  # 把 hello 包换成我的版本
  hello = super.hello.override {
    # 修改参数
  };
}

️ Common uses for Overlays#

1. Change build options (Override)

Some packages have certain features disabled by default at build time.

(self: super: {
  mpv = super.mpv.override {
    scripts = [ self.mpvScripts.mpris ];
  };
})

2. Apply patches (overrideAttrs)

If you have a .patch file:

(self: super: {
  sl = super.sl.overrideAttrs (oldAttrs: {
    patches = (oldAttrs.patches or []) ++ [ ./my-patch.patch ];
  });
})

3. Add a new package

You can define your own package in an Overlay and then reference it as pkgs.my-app.

Integrate Overlays into a Flake#

Define your Overlays in the outputs section.

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  outputs = { self, nixpkgs, ... }: {
    overlays.default = final: prev: {
      sl = prev.sl.overrideAttrs (old: {
        patches = (old.patches or []) ++ [ ./my-patch.patch ];
      });
    };
    nixosConfigurations.workstation = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        { nixpkgs.overlays = [ self.overlays.default ]; }
      ];
    };
  };
}

Why do this?#

As an Arch user, you may be used to finding PKGBUILDs in the AUR. In NixOS, Overlays are your all-purpose customization tool. You do not need to repackage software from scratch; you can simply adjust an existing package.

Summary#

• override: Changes the arguments to a package function (usually the function arguments supplied by callPackage).
• overrideAttrs: Changes the derivation attributes passed to mkDerivation (such as patches and postInstall), producing a new derivation.

final / prev and actual builds

self: super: is an older variable-naming convention; final: prev: is more descriptive, referring to the final package set after all overlays and the package set from the previous layer, respectively. After importing an overlay, you must still ensure that consumers actually use that package set. The original example only defined a local pkgs without connecting it to nixosSystem; here it has been changed to nixpkgs.overlays in a module. Patch changes require an actual build of the affected package: successful evaluation does not prove that a patch applies. The pinned Nixpkgs determines the package function's arguments and version.