Frequently asked questions and common newcomer trouble should be put here so that we can point to this page instead of answering the same question over and over again.

http://unix.stackexchange.com/questions/tagged/nixos can also be used for questions.

Why is Nix written in C++ rather than a functional language like Haskell or OCaml, given the strong influence that functional programming has obviously had on Nix

Mainly because Nix is intended to be lightweight, easy to learn and portable (zero dependencies). Since 24. April 2017 thanks to Shea Levy and the crowdfunding of 54 community members, nix does not have Perl as dependency anymore.

I installed a library but my compiler is not finding it. Why?

With nix, only applications should be installed into profiles. Libraries are used using nix-shell. If you want to compile a piece of software that requires zlib and uses pkg-config to discover it, run nix-shell -p pkgconfig zlib to get into a shell with the appropriate environment variables set. In there, a configure script will work as expected.

This applies to other language environments too. In some cases the expressions to use are a bit different, e.g. because the interpreter needs to be wrapped to have some additional environment variables passed to it. The manual has a section on the subject.

If you have a lot of dependencies, you may want to write a nix expression that includes your dependencies so that you can simply use nix-shell rather than writing out each dependency every time or keeping your development environment in your shell history. A minimal example looks like this:

# default.nix
with import <nixpkgs> {};
stdenv.mkDerivation {
    name = "dev-environment"; # Probably put a more meaningful name here
    buildInputs = [ pkgconfig zlib ];
}

Why does it work like that?

This helps ensure purity of builds: on other distributions, the result of building a piece of software may depend on which other software you have installed. Nix attempts to avoid this to the greatest degree possible, which allows builds of a piece of software to be identical (in the ideal case) no matter where they're built, by requiring all dependencies to be declared.

How to keep build-time dependencies around / be able to rebuild while being offline?

# /etc/nixos/configuration.nix
{ config, pkgs, lib, ... }:
{
  nix.extraOptions = ''
    gc-keep-outputs = true
    gc-keep-derivations = true
  '';
}

Check 'man configuration.nix' for these options. Rebuild for these options to take effect:

nixos-rebuild switch

List all store paths that form the system closure and realise them:

nix-store -qR $(nix-instantiate /etc/nixos/nixos -A system) | xargs nix-store -r
warning: you did not specify `--add-root'; the result might be removed by the garbage collector

<build output and list of successfully realised paths>

Repeat for your user and further profiles:

nix-store -qR ~/.nix-profile |xargs nix-store -r

The warning can be ignored for profiles that are listed/linked in /nix/var/nix/profiles/ or one of its subdirectories.

Consult man pages of nix-store and nix-instantiate for further information.

Why <hash>-<name> instead of <name>-<hash>?

For the rare cases where we have to dig into the /nix/store it is more practical to keep in mind the first few letters at the beginning than finding a package by name. In addition, the hash is printed by Nix commands. If you still wonder why, run ls -1 /nix/store | sort -R -t - -k 2 | less in your shell.

This is what might happen if you don't garbage collect frequently, or if you are testing compilation variants:

q0yi2nr8i60gm2zap46ryysydd2nhzhp-automake-1.11.1/
vbi4vwwidvd6kklq2kc0kx3nniwa3acl-automake-1.11.1/
wjgzir57hcbzrq3mcgxiwkyiqss3r4aq-automake-1.11.1/
1ch5549xnck37gg2w5fh1jgk6lkpq5mc-nixos-build-vms/
4cmjlxknzlvcdmfwj0ih0ggqsj5q73hb-nixos-build-vms/
7fv4kwi5wwwzd11ili3qwg28xrj8rxw2-nixos-build-vms/
8jij13smq9kdlqv96hm7y8xmbh2c54iy-nixos-build-vms/
j714mv53xi2j4ab4g2i08knqr137fd6l-nixos-build-vms/
xvs7y09jf7j48p6l0p87iypgpq470jqw-nixos-build-vms/

I've updated my channel and something is broken, how can I rollback to an earlier channel?

View the available generations of your channel:

nix-env --list-generations -p /nix/var/nix/profiles/per-user/root/channels
18   2014-04-17 09:16:28
19   2014-06-13 10:31:24 
20   2014-08-12 19:09:20   (current)

To rollback to the previous generation:

nix-env --rollback -p /nix/var/nix/profiles/per-user/root/channels
switching from generation 20 to 19

To switch to a particular generation:

nix-env --switch-generation 18 -p /nix/var/nix/profiles/per-user/root/channels
switching from generation 20 to 18

I'm working on a new package, how can I build it without adding it to nixpkgs?

nix-build -E 'with import <nixpkgs> { }; callPackage ./mypackage.nix { }'

You can replace callPackage with callPackage_i686 to build the 32-bit version of your package on a 64-bit system if you want to test that.

How can I compile a package with debugging symbols included?

To build a package with -O0 and -g, and without stripping debug symbols use:

nix-build -E 'with import <nixpkgs> { }; enableDebugging fooPackage'

How can I force a rebuild from source even without modifying the nix expression?

As root you can run nix-build with the --check flag:

sudo nix-build --check -A ncdu

How can I manage software with nix-env like with configuration.nix?

There are many ways, one is the following:

Create a meta package called userPackages your ~/.config/nixpkgs/config.nix file with the packages you would like to have in your environment:

with (import <nixpkgs> {});
{
  packageOverrides = pkgs: with pkgs; {
  userPackages = buildEnv {
    inherit ((import <nixpkgs/nixos> {}).config.system.path)
    pathsToLink ignoreCollisions postBuild;
    extraOutputsToInstall = [ "man" ];
    name = "user-packages";
    paths = [ vim git wget ];
  };
}

Install all specified packages using this command:
```
nix-env -iA userPackages -f '<nixpkgs>'
```

Now you can add and remove packages from the paths list and rerun nix-env to update your user local packages.

I've downloaded a binary, but I can't run it, what can I do?

It probably just needs to know where to find the libraries it needs. You can use patchelf to set the library path and dynamic linker appropriately:

# mybinaryprogram.nix
with import <nixpkgs> {}; with xlibs;
stdenv.mkDerivation rec {
  name = "somename";
  buildInputs = [ makeWrapper ];
  buildPhase = "true";
  libPath = lib.makeLibraryPath [ libXrandr libXinerama libXcursor ];
  unpackPhase = "true";
  installPhase = ''
    mkdir -p $out/bin
    cp ${./mybinaryprogram} $out/bin/mybinaryprogram
    patchelf \
    --set-interpreter "$(< "$NIX_CC/nix-support/dynamic-linker")" \
    --set-rpath "${libPath}" \
    $out/bin/mybinaryprogram
  '';
}

This can be built with:

nix-build mybinaryprogram.nix

And run with:

./result/bin/mybinaryprogram

Another possibility is using a FHS-compatible Sandbox with buildFHSUserEnv

# fhsUser.nix
{ pkgs ? import <nixpkgs> {} }:
(pkgs.buildFHSUserEnv {
  name = "example-env";
  targetPkgs = pkgs: with pkgs; [
    coreutils
  ];
  multiPkgs = pkgs: with pkgs; [
    zlib
    xorg.libXxf86vm
    curl
    openal
    openssl_1_0_2
    xorg.libXext
    xorg.libX11
    xorg.libXrandr
    mesa_glu
  ];
  runScript = "bash";
}).env

the sandbox can be entered with

nix-shell fhsUser.nix

What are channels and how they get updated?

Nixpkgs is the git repository containing all packages and NixOS modules/expressions. Installing packages directly from Nixpkgs master branch is possible but a bit risky as git commits are merged into master before being heavily tested. That's where channels are useful.

A "channel" is a name for the latest "verified" git commits in Nixpkgs. Each channel has a different definition of what "verified" means. Each time a new git commit is verified, the channel declaring this verification gets updated. Contrary to an user of the git master branch, a channel user will benefit both from verified commits and binary packages from the binary cache.

Channels are reified as git branches in the nixpkgs-channels repository and as disk images in the channels webpage. There are several channels, each with its own use case and verification phase:

nixos-unstable
description Use this when you want the latest package and module versions while still benefiting from the binary cache. You can use this channel on non-NixOS systems. This channel corresponds to NixOS’s main development branch, and may thus see radical changes between channel updates. This channel is not recommended for production systems.
definition this channel is updated depending on release.nix and release-lib.nix
nixos-unstable-small
description This channel is identical to nixos-unstable described above, except that this channel contains fewer binary packages. This means the channel gets updated faster than nixos-unstable (for instance, when a critical security patch is committed to NixOS’s source tree). However, the binary cache may contain less binary packages and thus using this channel may require building more packages from source than nixos-unstable. This channel is mostly intended for server environments and as such contains few GUI applications.
definition this channel is updated depending on release-small.nix and release-lib.nix
nixos-YY.MM (where YY is a 2-digit year and MM is a 2-digit month, such as nixos-17.03)
description These channels are called stable and only get conservative bug fixes and package upgrades. For instance, a channel update may cause the Linux kernel on your system to be upgraded from 3.4.66 to 3.4.67 (a minor bug fix), but not from 3.4.x to 3.11.x (a major change that has the potential to break things). Stable channels are generally maintained until the next stable branch is created.
definition this channel is updated depending on release.nix and release-lib.nix
nixos-YY.MM-small (where YY is a 2-digit year and MM is a 2-digit month, such as nixos-15.09-small)
description The difference between nixos-YY.MM-small and nixos-YY.MM is the name as the one between nixos-unstable-small and nixos-unstable (see above)

Channel update works as follows:

Each channel has a particular job at hydra.nixos.org which must succeed:

For NixOS: the trunk-combined tested job, which contains some automated NixOS tests.
For nixos-small: the unstable-small tested job.
For nixpkgs: the trunk unstable job, which contains some critical release packages.

Once the job succeeds at a particular nixpkgs commit, cache.nixos.org will download binaries from hydra.nixos.org.
Once the above download completes, the channel updates.

You can checkout the nixpkgs git and reset it to a particular commit of a channel. This will not affect your access to the binary cache.

How do I know where's nixpkgs channel located and at which commit?

First echo $NIX_PATH to see where nix looks for the expressions. Note that nix-env uses ~/.nix-defexpr regardless of $NIX_PATH.

If you want to know where <nixpkgs> is located:

nix-instantiate --find-file nixpkgs

To know the commit, open the .version-suffix file in the nixpkgs location. The hash after the dot is the git commit.

An error occurs while fetching sources from an url, how do I fix it?

First try to update the local nixpkgs expressions with nix-channel --update (these describe where to download sources from and how to build them). Try your build again and the url might have already been correctly updated for the package in question. You can also subscribe the unstable channel (which includes the most up-to-date expressions) with nix-channel --add http://nixos.org/channels/nixpkgs-unstable, update and try the build again.

If that fails you can update the url in the nix expression yourself. Navigate to your channel's expressions and find the package in one of the subdirectories. Edit the respective default.nix file by altering the url and sha256. You can use nix-prefetch-url url to get the SHA-256 hash of source distributions.

If the shell complains that you do not have write privileges for the file system, you will have to enable them.

start a new shell with a private mount namespace (Linux-only)

sudo unshare -m bash

remount the filesystem with write privileges (as root)

mount -o remount,rw /nix/store

update the file

nano <PATH_TO_PACKAGE>/default.nix

exit to shell where /nix/store is still mounted read-only

exit

Be sure to report the incorrect url or fix it yourself.

How do I know the sha256 to use with fetchgit/fetchsvn/fetchbzr/fetchcvs?

Install nix-prefetch-scripts and use the corresponding nix prefetch helper.

For instance to get the checksum of a git repository use:

nix-prefetch-git https://git.zx2c4.com/password-store

Should I use http://hydra.nixos.org/ as a binary cache?

Short answer: no.

http://cache.nixos.org is hosted on AWS S3, so it is fast and efficient, but it only contains binaries for nix channels (nixos-unstable, nixpkgs-unstable, and some stable channels too).

So, if the channel is way behind, you may see recommendations to add http://hydra.nixos.org/ as a binary cache, as it contains all recent builds, including ones not pushed to channels.

Unfortunately, due to poor caching, http://hydra.nixos.org/ needs to calculate what is available every time you ask about substitutes, so using it regularly as a cache will slow down the build machines.

Thus, the recommended configuration is to not put http://hydra.nixos.org/ in any config file or automated script. But if you are working on nixpkgs master, then the binary cache provided by Hydra can be very helpful. In such a case, you can add the Hydra cache to the trusted binary caches in nix.conf or configuration.nix, restart the Nix daemon, and use --option extra-binary-caches http://hydra.nixos.org/ in whatever commands are convenient.

I'm trying to install NixOS but my Wifi isn't working and I don't have an ethernet port

Most phones will allow you to share your Wifi connection over USB. On Android you can enable this setting via Settings > Wireless & Networks / More ... > Tethering & portable hotspot > USB tethering. This should be enough to allow you to install NixOS, and then fix your Wifi. iPhones only let you tether using your data connection rather than WiFi.

How can I disable the binary cache and build everything locally?

Set the binary caches to an empty list: nix.binaryCaches = []; in _configuration.nix or pass ad-hoc --option binary-caches "" as parameter to nix-build or its wrappers.

This is also useful to make simple configuration changes in NixOS (ex.: network related), when no network connectivity is available:

nixos-rebuild switch --option binary-caches ""

How do I enable chrooted builds on non-NixOS?

Two options have to be added to make chrooted builds work on Nix, build-use-chroot and build-chroot-dirs:

# /etc/nix/nix.conf
build-use-chroot = true
build-chroot-dirs = $(nix-store -qR $(nix-build '<nixpkgs>' -A bash) | xargs echo /bin/sh=$(nix-build '<nixpkgs>' -A bash)/bin/bash)

On NixOS set the following in configuration.nix:

nix.extraOptions = ''
  build-use-sandbox = true
'';

I cannot find $package when running `nix-env -qaP` even with channels configured

Not all packages are listed. Packages may not be listed because: - the package is unfree, like e.g. unrar and teamspeak_client; - the package is part of an attribute set and nix-env doesn't recurse into this set (see pkgs.recurseIntoAttrs)

How can I install a proprietary or unfree package?

If you want to install an unfree package as a user, then you need to enable it in ~/.nixpkgs/config.nix:

{
  ...
  allowUnfree = true;
}

If you want to enable unfree packages system-wide, then set in your /etc/nixos/configuration.nix:

{
  ...
  nixpkgs.config.allowUnfree = true;
}

For temporary allowing unfree packages you can set the environment variable NIXPKGS_ALLOW_UNFREE, e.g.

NIXPKGS_ALLOW_UNFREE=1 nix-env

How can I install a package from unstable while remaining on the stable channel?

It is possible to have multiple nix-channels simultaneously. To add the unstable channel with the specifier unstable,

sudo nix-channel --add https://nixos.org/channels/nixos-unstable unstable

After updating the channel

sudo nix-channel --update unstable

queries via nix-env (or nox) will show packages from both stable and unstable. Use this to install unstable packages into your user environment. The following snippet shows how this can be done in configuration.nix.

{ config, pkgs, ... }:
let
  unstable = import <nixos-unstable> {};
in {
  environment.systemPackages = [ unstable.PACKAGE_NAME ];
}

What is the origin of the name `Nix`

The name Nix is derived from the Dutch word niks, meaning nothing;build actions do not see anything that has not been explicitly declared as an input > Nix: A Safe and Policy-Free System for Software Deployment, page 2

Navigation menu

FAQ

Contents

Why is Nix written in C++ rather than a functional language like Haskell or OCaml, given the strong influence that functional programming has obviously had on Nix

I installed a library but my compiler is not finding it. Why?

Why does it work like that?

How to keep build-time dependencies around / be able to rebuild while being offline?

Why <hash>-<name> instead of <name>-<hash>?

I've updated my channel and something is broken, how can I rollback to an earlier channel?

I'm working on a new package, how can I build it without adding it to nixpkgs?

How can I compile a package with debugging symbols included?

How can I force a rebuild from source even without modifying the nix expression?

How can I manage software with nix-env like with configuration.nix?

I've downloaded a binary, but I can't run it, what can I do?

What are channels and how they get updated?

How do I know where's nixpkgs channel located and at which commit?

An error occurs while fetching sources from an url, how do I fix it?

How do I know the sha256 to use with fetchgit/fetchsvn/fetchbzr/fetchcvs?

Should I use http://hydra.nixos.org/ as a binary cache?

I'm trying to install NixOS but my Wifi isn't working and I don't have an ethernet port

How can I disable the binary cache and build everything locally?

How do I enable chrooted builds on non-NixOS?

I cannot find $package when running `nix-env -qaP` even with channels configured

How can I install a proprietary or unfree package?

How can I install a package from unstable while remaining on the stable channel?

What is the origin of the name `Nix`

FAQ

Why is Nix written in C++ rather than a functional language like Haskell or OCaml, given the strong influence that functional programming has obviously had on Nix

I installed a library but my compiler is not finding it. Why?

Why does it work like that?

How to keep build-time dependencies around / be able to rebuild while being offline?

Why <hash>-<name> instead of <name>-<hash>?

I've updated my channel and something is broken, how can I rollback to an earlier channel?

I'm working on a new package, how can I build it without adding it to nixpkgs?

How can I compile a package with debugging symbols included?

How can I force a rebuild from source even without modifying the nix expression?

How can I manage software with nix-env like with configuration.nix?

I've downloaded a binary, but I can't run it, what can I do?

What are channels and how they get updated?

How do I know where's nixpkgs channel located and at which commit?

An error occurs while fetching sources from an url, how do I fix it?

How do I know the sha256 to use with fetchgit/fetchsvn/fetchbzr/fetchcvs?

Should I use http://hydra.nixos.org/ as a binary cache?

I'm trying to install NixOS but my Wifi isn't working and I don't have an ethernet port

How can I disable the binary cache and build everything locally?

How do I enable chrooted builds on non-NixOS?

I cannot find $package when running nix-env -qaP even with channels configured

How can I install a proprietary or unfree package?

How can I install a package from unstable while remaining on the stable channel?

What is the origin of the name Nix

I cannot find $package when running `nix-env -qaP` even with channels configured

What is the origin of the name `Nix`