4. Build a package using Nix

Quick start / Build a package using Nix
Guide 4 of 8
In this guide

Build a Nix package defined in Nixpkgs

Run the package from the local directory

Initialize a flake template in your preferred programming language

Build a Nix package from the flake.nix in the template

While Nix can do many things, package management is the thing that it's perhaps best known for. In this tutorial, we'll use our installed Nix CLI to build and run some Nix packages included in Nixpkgs. Later in the guide we'll build and run a Nix package defined in a local flake.

Build a package from Nixpkgs

Let's start by building bat, a syntax-highlighted version of cat written in Rust that has a Nix package defined in Nixpkgs, in an empty directory (make sure to run this in a directory where you have write access):

mkdir build-nix-package && cd build-nix-package
nix build "nixpkgs#bat"

Here, nixpkgs is a flake reference to the NixOS/nixpkgs repository on GitHub, while #bat indicates that we're building the bat output from the Nixpkgs flake.

When the build is done, run ls . and you should see something called result in the current directory. result is actually a symlink to the built package in the Nix store, which you can verify:

readlink result

You should see a path like this (it's likely to be a bit different on your machine):

/nix/store/ 1. Nix store prefix
sglc12hc6pc68w5ppn2k56n6jcpaci16 2. Hash part
bat-0.22.1 3. Package name

What's happened here is that the Nix CLI has:

  • Downloaded the Nix code in Nixpkgs
  • Found a package definition with the name bat (code here)
  • Used the build instructions for bat to build the package
  • Stored the result in the Nix store using Nix's hash-based path system

You can now run bat:

./result/bin/bat --help

🚀 Success! You've built and run a package using Nix.

Build a package for tools written in $LANGUAGE

One of the great things about Nix is that package builds are extremely flexible, which enables you to create packages for things written in just about any programming language. In this section, we'll explore that by building and running packages for tools written in a variety of languages. Select one below to see some examples:

Select your language

Let's build and run npm:

nix build "nixpkgs#nodePackages.npm"
./result/bin/npm --help

If you run ls result/bin you'll notice that the package also includes npx.

Beyond Nixpkgs

While Nixpkgs is by far the largest Nix package repository in the known universe, any Nix flake can include package outputs. Let's build a package from a different repo, this time the package for Home Manager, a popular Nix tool for configuring home environments:

nix build "github:nix-community/home-manager"

Here, github:nix-community/home-manager is a flake reference to the nix-community/home-manager repo on GitHub. To run Home Manager:

./result/bin/home-manager --help

Upstreaming your packages to Nixpkgs is always an option, but it's good to bear in mind that with Nix you can distribute packages via any public Git repository with a flake.nix.

Build a package in a local flake

Earlier in this guide, we built a Nix package defined in Nixpkgs to get a sense of some of the mechanics of that process. In this guide, we'll dig a bit deeper and build a Nix package defined in a local Nix flake.

As above, select a preferred language:

Select your language

To get started in your JavaScript project, create an empty directory and initialize a flake template:

mkdir nix-javascript-pkg && cd nix-javascript-pkg
nix flake init --template "github:DeterminateSystems/zero-to-nix#javascript-pkg"

Whichever language you've selected, you can build the Nix package defined in the local flake by running:

nix build

This command determines that the local flake has a package output that defines how the package is built. In this particular flake there's a default package, which enables us to run nix build without specifying an output, but if the package were output as packages.mypkg, for example, we'd need to run nix build .#mypkg to build it.

Here's the package definition that builds our JavaScript package:

  packages.default = pkgs.buildNpmPackage {
    name = "zero-to-nix-javascript";

    # The packages required by the build process
    buildInputs = [

    # The code sources for the package
    src = ./.;
    npmDepsHash = "sha256-8Bj7nPZBAU+SnVTeKeArcjYnfZV4z/4I7fX+l0V+v04=";

    # How the output of the build phase
    installPhase = ''
      mkdir $out
      npm run build
      cp dist/index.html $out

For the full flake, see flake.nix on GitHub or run cat flake.nix. What you see here is a derivation that defines how to build the package, more specifically the buildNpmPackage function, which is a wrapper around Nix's built-in derivation function.

The package that results when you run nix build is a website built using the [Vite] framework. To view that website, open the HTML file at result/index.html.

We won't delve too much deeper into derivations and creating your own packages here, but we hope that this guide shows you how Nix code gets turned into real build output.

Was this page helpful?