---
title: "NixOS: The DOs and DON'Ts of nixpkgs overlays"
description: "Overlays are the new standard mechanism to customize nixpkgs. They replace constructs like packageOverride and overridePackages."
language: en
date: 2024-04-02
canonical: "https://flyingcircus.io/en/about-us/blog-news/details-view/nixos-the-dos-and-donts-of-nixpkgs-overlays"
format: markdown
generator: "TYPO3 LLMs.txt Extension"
---

# NixOS: The DOs and DON'Ts of nixpkgs overlays

> Overlays are the new standard mechanism to customize nixpkgs. They replace constructs like packageOverride and overridePackages.

# NixOS: The DOs and DON'Ts of nixpkgs overlays

  Created by Christian Kauhaus |     11/07/2017  |  Blog

 Overlays are the new standard mechanism to customize nixpkgs. They replace constructs like packageOverride and overridePackages.

 One presentation at [NixCon 2017](http://nixcon2017.org/) that especially drew my attention was [Nicolas Pierron](https://twitter.com/nbpname)'s talk about **Nixpkgs overlays** ([video](https://youtu.be/6bLF7zqB7EM?t=39m50s), [slides](http://nbp.github.io/slides/NixCon/2017.NixpkgsOverlays/)). I'd like to give a quick summary here for future reference. All the credits go to Nicolas, of course.

## What are overlays?

Overlays are the new standard mechanism to customize nixpkgs. They replace constructs like *packageOverride* and *overridePackages*.

## How do I use overlays?

Put your overlays into *~/.config/nixpkgs/overlays*. All overlays share a basic structure:

```
self: super: {
  …
}
```

Arguments:

- **self** is the result of the fix point calculation. Use it to access packages which could be modified somewhere else in the overlay stack.
- **super** one overlay down in the stack (and base nixpkgs for the first overlay). Use it to access the package recipes you want to customize, and for library functions.

## Good examples

### Add default proxy to Google Chrome

```
self: super:
{
   google-chrome = super.google-chrome.override {
     commandLineArgs =
       "--proxy-server='https=127.0.0.1:3128;http=127.0.0.1:3128'";
   };
}
```

From [Alexandre Peyroux](https://spof.px.io/~alex/posts/2017-05-15-nixos-overlay.html).

### Fudge Nix store location

```
self: super:
{
  nix = super.nix.override {
    storeDir = "${}/store";
     stateDir = "${}/var";
   };
}
```

From [Yann Hodique](http://yann.hodique.info/blog/nix-in-custom-location/).

### Add custom package

```
self: super:
{
  VidyoDesktop = super.callPackage ./pkgs/VidyoDesktop { };
}
```

From [Mozilla](https://github.com/mozilla/nixpkgs-mozilla/).

## Bad examples

### Recursive attrset

```
self: super: rec {
   fakeClosure = self.writeText "fake-closure.nix" ''
     …
   '';
   fakeConfig = self.writeText "fake-config.nix" ''
    (import ${fakeClosure} {}).config.nixpkgs.config
  '';
}
```

Two issues:

- Use super to access library functions.
- Overlays should not be recursive. Use self.

### Surplus arguments

```
{ python }:
self: super:
{
  "execnet" =
    python.overrideDerivation super."execnet" (old: {
      buildInputs = old.buildInputs ++ [ self."setuptools-scm" ];
    });
}
```

The issue:

- Overlays should depend just on self and super in order to be composeable.

### Awkward nixpkgs import

```
{ pkgs ? import  {} }:
let
  projectOverlay = self: super: {
    customPythonPackages =
      (import ./requirements.nix { inherit pkgs; }).packages;
  };
in
import pkgs.path {
  overlays = [ projectOverlay ];
}
```

Two issues:

- Unnecessary double-import of nixpkgs. This might break cross-system builds.
- *requirements.nix* should use self not pkgs.

#### Improved version

*shell.nix*:

```
{ pkgsPath ?  }:
import pkgsPath {
  overlays = [ import ./default.nix; ];
}
```

*default.nix*:

```
self: super:
{
 customPythonPackages =
   (import ./requirements.nix { inherit self; }).packages;
}
```

### Incorrectly referenced dependencies

```
self: super:
let inherit (super) callPackage;
in {
  radare2 = callPackage ./pkgs/radare2 {
    inherit (super.gnome2) vte;
    lua = super.lua5;
  };
}
```

The issue:

- Other packages should be taken from self not super. This way they can be overridden by other overlays.

### Overridden attrset

```
self: super:
{
  lib = {
    firefoxVersion = … ;
  };
  latest = {
    firefox-nightly-bin = … ;
    firefox-beta-bin = … ;
    firefox-bin = … ;
    firefox-esr-bin = … ;
  };
}
```

The issue:

- Other attributes present in lib and latest from down the overlay stack are erased.

#### Improved version

Always extend attrsets in overlays:

```
self: super:
{
  lib = (super.lib or {}) // {
    firefoxVersion = … ;
  };
  latest = (super.latest or {}) // {
    …
  };
}
```

## Summary

I hope this condensed guide helps you to write better overlays. For in-depth discussion, please go watch Nicolas' [talk](https://youtu.be/6bLF7zqB7EM?t=39m50s) and read the [Nixpkgs manual](https://nixos.org/nixpkgs/manual/#chap-overlays). Many thanks to Nicolas for putting this together!

  [ Back ](https://flyingcircus.io/en/about-us/blog-news.md)