Overlays

Details

Files in this directory run automatically as part of each build. Overlays allow you to override the configuration of certain packages so that they behave in a specific way. Common use cases for overlays include:

  • Applying patches

  • Downloading different versions of files (locking to a version or trying a fork)

  • Implementing temporary workarounds

  • Renaming or defining new packages

Overlays are activated when defining your pkgs from nixpkgs in flake.nix. This is the cleanest way to override anything, so if you need to do so, please add files to this folder.

For instance, you can override the version of a package (e.g., starship) by using the mpkgs input, which follows the nixpkgs master branch. This is useful if you need the latest available package for some packages without having to update the entire nixpkgs channel, which could risk breaking your configuration.

The import logic is defined in overlays/default.nix.

  • It enables passing arguments to overlays if required, such as system or mpkgs. This can be extended by adding more inputs in the flake.nix, or by adding overlay-specific inputs in overlays/default.nix.

  • The default overlay logic should not be erased and generally does not need modification.

Adding Custom Packages

If you need a package or tool (for example, from a GitHub repository) that cannot be found in the official Nixpkgs repository, or if you want to override the build process or patch a package in a way that is not possible through overlays or upstream Nixpkgs, you can define custom packages in this directory.

  • Each .nix file (except default.nix) should define one or more packages as Nix attributes.

  • The default.nix file automatically imports all other .nix files in this directory and aggregates their outputs.

  • The resulting set of packages is imported in the main flake.nix and can be added to your development shell or used elsewhere in your project.

Example

To add a custom package, create a new file (e.g., mytool.nix) in this directory:

self: super:

{
  mytool = super.stdenv.mkDerivation {
    pname = "mytool";
    version = "1.0.0";
    src = super.fetchFromGitHub {
      owner = "username";
      repo = "mytool";
      rev = "commit-or-tag";
      sha256 = "sha256-...";
    };
    buildPhase = "true";
    installPhase = ''
      mkdir -p $out/bin
      cp $src/mytool $out/bin/
      chmod +x $out/bin/mytool
    '';
  };
}

This will make mytool available as a package pkgs. You must then register it under your packages wherever needed by calling pkgs.mytool.

See tmp.nix for another commented template to help you get started.

Tip: Use this folder only for packages that cannot be obtained or easily overridden from upstream Nixpkgs.

Resources