Overlays

Added in 1.4.2

Overlays in devenv allow you to modify or extend the default package set (pkgs) that devenv uses. This is useful when you need to:

• Override existing packages to apply patches
• Add new packages that aren’t in the default set
• Use custom builds of existing packages

Using overlays

To add overlays to your devenv configuration, use the overlays option in your devenv.nix file:

{ pkgs, ... }:
{  # List of overlays to apply to pkgs  overlays = [    # Each overlay is a function that takes two arguments: final and prev    (final: prev: {      # Override an existing package      hello = prev.hello.overrideAttrs (oldAttrs: {        patches = (oldAttrs.patches or []) ++ [ ./hello-fix.patch ];      });
      # Add a custom package      my-custom-package = final.callPackage ./my-package.nix {};    })  ];
  # Now you can use the modified or added packages  packages = [ pkgs.hello pkgs.my-custom-package ];}

How overlays work

Each overlay is a function that takes two arguments:

• final: The final package set after all overlays are applied
• prev: The package set as it existed before this overlay (but after previous overlays)

The function should return an attrset containing the packages you want to add or modify. These will be merged into the final package set.

Common use cases

Patching existing packages

overlays = [  (final: prev: {    # Apply a patch to fix a bug    somePackage = prev.somePackage.overrideAttrs (oldAttrs: {      patches = (oldAttrs.patches or []) ++ [ ./my-fix.patch ];    });  })];

Using a different version of a package

overlays = [  (final: prev: {    # Use a specific version of Node.js    nodejs = prev.nodejs-18_x;  })];

Adding custom packages

overlays = [  (final: prev: {    # Add a package from a local derivation    my-tool = final.callPackage ./nix/my-tool.nix {};  })];

Using packages from older nixpkgs

First, add the extra input to your devenv.yaml:

inputs:  nixpkgs:    url: github:cachix/devenv-nixpkgs/rolling  nixpkgs-unstable:    url: github:nixos/nixpkgs/nixpkgs-unstable

Then use it in your devenv.nix:

{ pkgs, inputs, ... }:
{  overlays = [    (final: prev: {      # Use a package from nixpkgs-unstable      nodejs = (import inputs.nixpkgs-unstable {        system = prev.stdenv.system;      }).nodejs;    })  ];
  # Now you can use these packages from your regular pkgs  languages.javascript.enable = true;}

Last updated Oct 08, 2026