Nixpkgs

Nixpkgs is the largest repository of Nix packages and NixOS modules. The repository is hosted on GitHub and maintained by the community, with official backing from the NixOS Foundation.

Channels

Main article: Nix Channels

The packages and modules hosted on Nixpkgs are sorted in various channels intended for various use-cases, and in practice are differentiated by the level of testing updates must pass on the official nixos.org hydra instance and the number of updates propagated to the channel.

For Nix users, nixpkgs-unstable is the bleeding-edge, where packages pass only basic build tests and are upgraded continuously.

For NixOS users, nixos-unstable is the bleeding-edge, where packages pass build tests and integration tests on a VM, and are tested from the perspective of being an operative system (this means things like the X server, KDE, various servers, and lower level details like installing bootloaders and runnning the nixos installation steps are also tested).

Both Nix and NixOS users can use stable channels - the latest being nixos-18.03 - to receive only conservative updates for fixing critical bugs and security vulnerabilities.

For more information on channels and how to select the appropriate channel for your purposes, see the Nix Channels article.

Contributing

Development in NixOS primarily driven by the work in nixpkgs on github. This repository contains both all packages available in your NixOS channel and all the options you can use for configuring your system with your configuration.nix. To get your text editor to recognize Nix expressions, consider installing a Nix Editor Modes for Nix Files.

Report issues

Any issue can be reported in the nixpkgs issue-tracker on github. Keep in mind that all work on nixpkgs is being done by volunteers and you cannot expect a quick response and solution for all problems you may face. In general Pull-Requests have a much shorter round-trip-time.

Create pull requests

If you want to see your package being provided by a channel, creating an issue will most likely not enough. It is up to you to create a nix package description in Nixpkgs and create a pull request in the Nixpkgs repository. Pull requests are a way to tell a github project that you've created some changes, which maintainers can easily review, comment on and, and finally merge into the repository.

Here's how to create a pull request on GitHub:

Fork Nixpkgs on Github

Create a GitHub account and fork nixpkgs/nixos/... repository.

Add a remote

On your host, create a new remote location:

# add your github clone as remote location:
YOUR_GITHUB_NAME=fill-in
git remote add $YOUR_GITHUB_NAME git@github.com:$YOUR_GITHUB_NAME/nixpkgs.git

Hack Nixpkgs

Make any modifications you want to your local copy of the repository, then build the package from the root of the nixpkgs directory with:

nix-build -A $yourpackage

The output of your build will be located under the result/ subdirectory. Try running the freshly built binaries in result/bin and check that everything is OK.

To test the changes on a NixOS machine, rebuild the system using your newly hacked Nixpkgs by executing:

sudo nixos-rebuild switch -I nixpkgs=/path/to/local/nixpkgs

Commit your change locally

Commit your change to your local clone of the repository:

git add FILE_LIST # use git add --patch as needed
git commit

==== Check status ====

Verify everything is ok - no unexpected dangling files git does not know about yet:
git status

Push to your remote repository

Submitting your change, push to your repository:

# recommended: create a topic branch, so that this change
# can be submitted independently from other patches:
git checkout -tb submit/your-topic-name
git push $YOUR_GITHUB_NAME submit/your-topic-name

Why create your own branch? You can follow upstream (master) by running git merge master. You can git commit --amend fixes and git push -f your branch. You can always switch back to master by git checkout master.

Create a pull request on GitHub

Go to the Nixpkgs repository and push the create pull request button. Add a description of your work and submit.

Manage your local repository

Tips & tricks for managing your nixpkgs checkout are kept in the page on git.

Becoming a Nixpkgs maintainer

There are two types of maintainer: Members of the NixOS organization and package/module maintainer.

Members of the NixOS organization have direct access to the nixpkgs and therefore can merge pull requests.

Everybody can become a package maintainer by adding to maintainers attribute in the meta section of a package. First add your nick handle (preferable your GitHub username) to maintainer-list.nix and reference the said handle within the package:

{ stdenv, fetchurl }:
stdenv.mkDerivation rec {
  name = "hello-2.10"; 
  # ....
  meta = with stdenv.lib; {
    # ...
    maintainers = with maintainers; [ eelco your-nick ]; # replace your-nick with your real nick
    platforms = platforms.all;
  };
}

There can be multiple maintainers per package. Maintainers will receive emails from Hydra when package builds enters a failed state. They do not have special privileges as everybody can suggest updates and modifications to any package. However they might be consulted by NixOS members for testing and as a domain experts, when somebody else make a change to a package.

Building all of the packages you maintain

Save as build.nix inside nixpkgs git clone. This snippet is based on maintainers/scripts/update.nix script.

{ pkgs ? import <nixpkgs> {}, maintainer }:

with pkgs.lib;

let
  maintainer_ = maintainers.${maintainer};

  packagesWith = cond: return: set:
      (pkgs.lib.flatten
        (pkgs.lib.mapAttrsToList
          (name: pkg:
            let
              result = builtins.tryEval (
                if pkgs.lib.isDerivation pkg && cond name pkg
                  then [(return name pkg)]
                else if pkg.recurseForDerivations or false || pkg.recurseForRelease or false
                  then packagesWith cond return pkg
                else []
              );
            in
              if result.success then result.value
              else []
          )
          set
        )
      );
in       
      packagesWith (name: pkg:
                                 (if builtins.hasAttr "maintainers" pkg.meta
                                   then (if builtins.isList pkg.meta.maintainers
                                           then builtins.elem maintainer_ pkg.meta.maintainers
                                           else maintainer_ == pkg.meta.maintainers
                                        )
                                   else false
                                 )
                   )
                   (name: pkg: pkg)
                   pkgs

Run the command:

nix-build build.nix --argstr maintainer your-nick

Alternatives

Due to the fact that nixpkgs is only a nix expression it is possible to extend or replace the logic with your own sources. In fact, there are a number of extensions as well as complete replacements for Nixpkgs, see the Alternative Package Sets article.

Subpages

There are a number of articles especially related to working with nixpkgs:

• Building RPM DEB with nixpkgs
• Contributing
• Create and debug packages
• en
• Modifying Packages
• Patching Nixpkgs
• Reviewing changes
• Update Scripts