From NixOS Wiki
Jump to: navigation, search

Overlays provide a method to extend and change nixpkgs. They replace constructs like packageOverride and overridePackages.

Consider a simple example of setting the default proxy in Google Chrome:

let overlay1 = self: super:
   google-chrome = super.google-chrome.override {
     commandLineArgs =

Applying overlays manually

import <nixpkgs> { overlays = [ overlay1 overlay2 ]; }

Applying overlays automatically

On the user level

A list of overlays placed into ~/.config/nixpkgs/overlays.nix will be automatically loaded by all nix tools.

Alternatively, you can put each overlay in its own .nix file under your ~/.config/nixpkgs/overlays directory.

On the system level

If you want your overlays to be accessible by nix tools and also in the system-wide configuration, add nixpkgs-overlays to your NIX_PATH:


Currently nixos-rebuild only works with a <nixpkgs-overlays> path that is a directory.

There is a configuration option nixpkgs.overlays. Overlays set here will not be automatically applied by nix tools.

Using nixpkgs.overlays from configuration.nix as <nixpkgs-overlays> in your NIX_PATH

This will allow all the Nix tools to see the exact same overlay as is defined in your configuration.nix in the nixpkgs.overlays option.

In configuration.nix, depending on whether your configuration.nix already defines nix.nixPath, add one of those definitions:

{ config, pkgs, options, ... }: {
  # With existing `nix.nixPath` entry:
  nix.nixPath = [
    # Add the following to existing entries.
  # Without any `nix.nixPath` entry:
  nix.nixPath =
    # Prepend default nixPath values.
    options.nix.nixPath.default ++ 
    # Append our nixpkgs-overlays.
    [ "nixpkgs-overlays=/etc/nixos/overlays-compat/" ]

And, add the file /etc/nixos/overlays-compat/overlays.nix[1]:

self: super:
with super.lib;
  # Using the nixos plumbing that's used to evaluate the config...
  eval = import <nixpkgs/nixos/lib/eval-config.nix>;
  # Evaluate the config,
  paths = (eval {modules = [(import <nixos-config>)];})
    # then get the `nixpkgs.overlays` option.
foldl' (flip extends) (_: super) paths self

External Documentation


  1. @samueldr's configuration: overlays-compat