Create custom package version in nix flake

You can create your own custom version of a package in case it is not available in any nix channel. This can be done with nix overlays and the function overrideAttrs.

Most of the time I just search for a package on the nix package page. There you can find packages with a specific pinned version. You could choose an alternative channel by linking a different version in you nix flake inputs. I described a basic setup in a previous article about nix flakes. It is even possible to import packages from multiple different channels. But it can happens that there is no available channel with the version you need. For example the required tool was already released with a newer version but no nix channel picked it up yet.

The good thing is that most of the time it is enough to add some small adjustments to an already existing nix package to create a custom version.

I will use par2cmdline as an example because I was trying to use version 1.0.0 in a project but the most recent channel (25.11 at the time of writing) does only provide version 0.8.1.

Find information about the available package

On the result page of nix packages you can click on a link called Homepage which will lead you to the project website. This is a git repo in our par2 example. On GitHub you can find releases for a repo and it corresponding git commit (par2 release v1.0.0).

Another link on the nix package result for par2cmdline is called Source. It shows the exact version of a package.nix which is used for the chosen nix channel. The file is like a build script for the tool.

The structure can vary from package to package. For some tools it might contain special custom scripts. The package recipe of par2cmdline is not to complicated. It only references the git repo with a specific version and uses some standard build tools which just work without any special configuration.

The following code block shows the relevant section:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# ...

stdenv.mkDerivation rec {
  pname = "par2cmdline";
  version = "0.8.1";

  src = fetchFromGitHub {
    owner = "Parchive";
    repo = "par2cmdline";
    rev = "v${version}";
    sha256 = "11mx8q29cr0sryd11awab7y4mhqgbamb1ss77rffjj6in8pb4hdk";
  };

# ...

Adjust required parameters to create a new version

In this case you can override parts of the package.nix file inside your nix flake configuration to create a new version.

This can be done via overlays. An overlay can change parts of the original package.nix on the fly. You can use a function called overrideAttrs to replace values.

The important lines of the nix flake example are highlighted below. Do not forget to add the overlays in the second highlighted section after the overlay definition too.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

{
  description = "nix flake dev shell";

  # Nixpkgs / NixOS version to use.
  inputs.nixpkgs.url = "nixpkgs/nixos-25.11"; # update in case you need newer versions

  outputs = { self, nixpkgs }:
    let

      # System types to support.
      supportedSystems = [ "x86_64-linux" "x86_64-darwin" "aarch64-linux" "aarch64-darwin" ];

      # Helper function to generate an attrset '{ x86_64-linux = f "x86_64-linux"; ... }'.
      forAllSystems = nixpkgs.lib.genAttrs supportedSystems;

      # Overlay to customize packages
      overlays = [
        (final: prev: {

          # set custom version for par2cmdline
          par2cmdline = prev.par2cmdline.overrideAttrs (oldAttrs: {
            version = "1.0.0";
            src = final.fetchFromGitHub {
              owner = "Parchive";
              repo = "par2cmdline";
              rev = "v1.0.0";
              sha256 = "sha256-io9Ofep3t2EJrHBX9gft+JJflYRp0bRX+zFnOFIAsTw=";
            };
          });
        })
      ];

      # Nixpkgs instantiated for supported system types.
      nixpkgsFor = forAllSystems (system: import nixpkgs { 
        inherit system; 
        overlays = overlays;
      });

    in
    {

      # Add dependencies that are only needed for development
      devShells = forAllSystems (system:
        let
          pkgs = nixpkgsFor.${system};

        in
        {
          default = pkgs.mkShellNoCC {  # or pkgs.mkShell (in case c compiler needed)
            packages = with pkgs; [
              # add packages here (search: https://search.nixos.org/packages)
              dar
              par2cmdline
              duckdb
            ];
          };
        });

    };
}

Hints for fetchFromGitHub parameters

We override values with overrideAttrs

• You have to add all parameters with the current one overlay (not only sha256)
• possible alternatives (I did not try this yet.)
  • perhaps by using another overlay only for inner sha256 this could be avoided
  • or by using oldAttrs inside the overlay. I also did not try this yet. I am not sure how the referenced version variable inside fetchFromGitHub gets overwritten then.
• for rev: I was not able to reference the variable with “v${version}”. This is why the version string is added manually to the again

Update sha256 hash value

• nix uses hashes to verify downloads and versions
• when changing the version of course the hashes changes too
• In a first step when defining the new version I set the sha256 hash attribute to a random valid value to ensure that no older valid hash gets verified and used
• when running checks and building the tool nix requires a valid sha256 format/length but the value is not important at first
• you can create a valid sha256 value by using this command

  echo -n "foobar" | shasum -a 256
• insert the hash value at the correct place
• then update the flake as described in my nix flake article
  • when running the following commands nix will throw an error because specified and got hashes are not the same
  • copy the sha256 hash value from the got line and insert at the sha256 attribute of your overlay.
    • different encodings seem to be work (base64 or also values in the format sha256-...=)

  nix flake check --all-systems
  nix flake update
  • test run the dev shell (forcing compile)
    • This step should throw the error in case the hashes do not match
    • for nix flakes the lockfile seems to be used too. So depending on the previous checks and flake updates the version validation takes information from the flake.lock file instead of the value in the overlay section of flake.nix

    nix develop

After updating the hash and a small test run via nix develop you can create a git commit for your changes to flake.nix and flake.lock.

Testing correct version

• open dev shell

  nix develop
• It should only take longer for the first time because nix will compile the package. The compiled version will be cached for the future
• Use the tool and check the version (example for par2)

  par2 --version
  • in this example it should return version 1.0.0 (it was 0.8.1 with the default version of the channel)

    par2cmdline version 1.0.0
  • otherwise something did not work with your nix flake update commands and provided hashes

Additional resources

• Reddit: Nix override vs overrideAattrs
• NixOS & Flakes Book: Overriding
• NixOS & Flakes Book: Overlays
• NixOS Wiki: Overriding a version with overlays
• Nixpkgs Manual: overrideAttrs
• Reddit: How to use different channels in a flake to configure NixOS?
• YouTube: Customize Nix Packages | Overrides & Overlays
  • flake overlay example at minute 05:50
• YouTube: Rebuilding my NixOS config - Part 15: Creating Custom Package Versions with Overrides and Overlays
• YouTube: Overlays and Version Pinning in the Nix-Config Overlays Module
• Nix Overlay post
• Nix forum: Help using overlays with flake-parts
• Nix flake sha256 git repo problem