How to create a package recipe

Important

For the list of all available configuration options for package recipes visit the package options reference.

Before writing a recipe, please spend some time to understand the software and gather the basic information from the package’s source code repository:

Metadata

• Package name, description

• Latest stable version

• Homepage URL

• License

• Main executable name

Language and build system

Look for these files in the repository root:

File	Build system
configure.ac or configure	Autotools (C/C++)
CMakeLists.txt	CMake (C/C++)
go.mod	Go
Makefile	Make (C/C++)
pyproject.toml or setup.py	Python
Cargo.toml	Rust

Dependencies — look in:

• CMakeLists.txt: find_package(), pkg_check_modules()

• configure.ac: PKG_CHECK_MODULES, AC_CHECK_LIB

• pyproject.toml / setup.py: [project.dependencies], install_requires

• README.md, INSTALL.md: listed prerequisites

• CI config (.github/workflows/, .gitlab-ci.yml): packages installed before build

Repository structure

• Are build files in the repository root or a subdirectory?

• Are there git submodules (.gitmodules file)?

• Does the build download anything at build time? Nix builds run without network access - these must be patched out or disabled via build flags.

Recipe file

Create the package recipe directory and recipe file:

mkdir recipes/pkgs/<package-name>
touch recipes/pkgs/<package-name>/recipe.nix

Add the recipe file to Git:

git add recipes/pkgs/<package-name>/recipe.nix

Important

Nix can only see recipe files tracked by Git. If the file is not added to Git, the package will not be recognized.

Metadata

Start the package recipe with the following content:

{
  pkgs,
  ...
}:

{
  pkgs.package-name = {        # lowercase with hyphens
    version = "1.0.0";           # latest released version
    description = "Short description of the package.";
    homePage = "https://project-website.org";
    mainProgram = "executable-name";
    license = lib.licenses.gpl3Only;

    # More configuration to be added here.
    # ...
  };
}

Important

Ensure that the remainder of the package recipe is done within the pkgs.package-name block to avoid nasty infinite recursion errors.

Note

Use the following command to get the list of all available licenses:

nix repl nixpkgs <<<':p lib.licenses'

Source

Add a source block pointing to the upstream release. Leave hash empty for now:

source = {
  git = "github:owner/repo/v1.0.0";
  hash = "";  # fill in after first build
};

For tarball releases use source.url.

If the repository uses git submodules, add source.submodules = true.

Builder

Enable exactly one builder and configure it as needed.

Condition	Builder
CMake, Autotools, or Makefile	builders.standard
Go	builders.go
Python with CLI tools ([project.scripts] or entry_points)	builders.python
Python library (no executables)	builders.pythonModule
Rust	builders.rust

Also, add dependencies using packages.build, packages.run or packages.check options.

build.builders.standard = {
  enable = true;

  # build-time dependencies
  packages.build = [
    pkgs.bison
    pkgs.boost
  ];

  # run-time dependencies
  packages.run = [
    pkgs.zlib
  ];
}

Run the first build:

nix build .#pkgs.<package-name> --print-build-logs

Nix will fail during the first build due to a missing source hash. Update source.hash with the value from the error output, then launch the build once again.

Troubleshooting

To troubleshoot build failures, enable debug mode to enter an interactive build environment:

build.debug = true;

Then launch the interactive build and follow the on-screen instructions. Press Ctrl-C to drop into a shell and start investigating.

mkdir dev && cd dev
nix develop .#pkgs.<package-name>

Tests

Add a test script to verify that package works correctly:

test.script = ''
  program --help | grep "Usage: program"
'';

Run test:

nix build .#pkgs.<package-name>.test --print-build-logs

Examples

Browse the example package recipes, or create your own Forge project to try them out:

nix flake init --template github:ngi-nix/forge#provider