Quick Start to Adding a Package
To add a package to Nixpkgs:
Checkout the Nixpkgs source tree:
$ git clone https://github.com/NixOS/nixpkgs $ cd nixpkgs
Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into
pkgs/development/libraries/pkgname, while a web browser goes into
pkgs/applications/networking/browsers/pkgname. See Coding conventions for some hints on the tree organisation. Create a directory for your package, e.g.
$ mkdir pkgs/development/libraries/libfoo
In the package directory, create a Nix expression — a piece of code that describes how to build the package. In this case, it should be a function that is called with the package dependencies as arguments, and returns a build of the package in the Nix store. The expression should usually be called
$ emacs pkgs/development/libraries/libfoo/default.nix $ git add pkgs/development/libraries/libfoo/default.nix
You can have a look at the existing Nix expressions under
pkgs/to see how it’s done. Here are some good ones:
pkgs/applications/misc/hello/default.nix. Trivial package, which specifies some
metaattributes which is good practice.
pkgs/tools/archivers/cpio/default.nix. Also a simple package. The generic builder in
stdenvdoes everything for you. It has no dependencies beyond
GNU Multiple Precision arithmetic library (GMP):
pkgs/development/libraries/gmp/5.1.x.nix. Also done by the generic builder, but has a dependency on
Pan, a GTK-based newsreader:
pkgs/applications/networking/newsreaders/pan/default.nix. Has an optional dependency on
gtkspell, which is only built if
pkgs/servers/http/apache-httpd/2.4.nix. A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery.
pkgs/applications/networking/mailreaders/thunderbird/default.nix. Lots of dependencies.
JDiskReport, a Java utility:
pkgs/tools/misc/jdiskreport/default.nix. Nixpkgs doesn’t have a decent
stdenvfor Java yet so this is pretty ad-hoc.
XML::Simple, a Perl module:
pkgs/top-level/perl-packages.nix(search for the
XMLSimpleattribute). Most Perl modules are so simple to build that they are defined directly in
perl-packages.nix; no need to make a separate file for them.
pkgs/applications/misc/adobe-reader/default.nix. Shows how binary-only packages can be supported. In particular the builder uses
patchelfto set the RUNPATH and ELF interpreter of the executables so that the right libraries are found at runtime.
metaattributes are optional, but it’s still a good idea to provide at least the
You can use
nix-prefetch-url urlto get the SHA-256 hash of source distributions. There are similar commands as
A list of schemes for
mirror://URLs can be found in
The exact syntax and semantics of the Nix expression language, including the built-in function, are described in the Nix manual in the chapter on writing Nix expressions.
Add a call to the function defined in the previous step to
pkgs/top-level/all-packages.nixwith some descriptive name for the variable, e.g.
$ emacs pkgs/top-level/all-packages.nix
The attributes in that file are sorted by category (like “Development / Libraries”) that more-or-less correspond to the directory structure of Nixpkgs, and then by attribute name.
To test whether the package builds, run the following command from the root of the nixpkgs source tree:
$ nix-build -A libfoo
libfooshould be the variable name defined in the previous step. You may want to add the flag
-Kto keep the temporary build directory in case something fails. If the build succeeds, a symlink
./resultto the package in the Nix store is created.
If you want to install the package into your profile (optional), do
$ nix-env -f . -iA libfoo
Optionally commit the new package and open a pull request to nixpkgs, or use the Patches category on Discourse for sending a patch without a GitHub account.