FAQ: Difference between revisions

<languages/>

<translate>

<!--T:1-->

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.

=== How to keep build-time dependencies around / be able to rebuild while being offline? === <!--T:3-->

<syntaxhighlight lang="nix"># /etc/nixos/configuration.nix

{ config, pkgs, lib, ... }:

   };

}</syntaxhighlight>

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

<!--T:32-->

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

<syntaxhighlight lang="bash">

nix-store -qR $(nix-instantiate '<nixpkgs/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>

</syntaxhighlight>

Repeat for your user and further profiles:

<!--T:35-->

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

<!--T:40-->

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

<syntaxhighlight lang="bash">

q0yi2nr8i60gm2zap46ryysydd2nhzhp-automake-1.11.1/

</syntaxhighlight>

=== I've updated my channel and something is broken, how can I rollback to an earlier channel? === <!--T:5-->

<!--T:42-->

View the available generations of your channel:

<syntaxhighlight lang="bash">

nix-env --list-generations -p /nix/var/nix/profiles/per-user/root/channels

20  2014-08-12 19:09:20  (current)

</syntaxhighlight>

To rollback to the previous generation:

<syntaxhighlight lang="bash">

nix-env --rollback -p /nix/var/nix/profiles/per-user/root/channels

switching from generation 20 to 19

</syntaxhighlight>

To switch to a particular generation:

<syntaxhighlight lang="bash">

nix-env --switch-generation 18 -p /nix/var/nix/profiles/per-user/root/channels

</syntaxhighlight>

=== I'm working on a new package, how can I build it without adding it to nixpkgs? === <!--T:6-->

<!--T:46-->

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.

<!--T:47-->

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

<syntaxhighlight lang="bash">nix-build -E 'with import <nixpkgs> { }; enableDebugging fooPackage'</syntaxhighlight>

<!--T:49-->

See also [[Debug Symbols]]

<!--T:50-->

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

<syntaxhighlight lang="bash">sudo nix-build --check -A ncdu</syntaxhighlight>

<!--T:52-->

There are many ways, one is the following:

<ol style="list-style-type: decimal;">

<syntaxhighlight lang="nix">

with (import <nixpkgs> {});

}

</syntaxhighlight></li>

<syntaxhighlight lang="bash">nix-env -iA userPackages -f '<nixpkgs>'</syntaxhighlight></li></ol>

<!--T:54-->

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

<!--T:9-->

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

Binaries normally do not work out of the box when you download them because they normally just assume that libraries can be found in hardcoded paths such as <code>/lib</code>. However this assumption is incorrect on NixOS systems due to the inner workings of <code>nix</code> - there is no default path, everything gets set to the corresponding version on compile time.

<!--T:58-->

You can use [https://github.com/Mic92/nix-ld nix-ld] to run compiled binaries. For example, if your binary needs zlib and openssl:

<syntaxhighlight lang="nix">

programs.nix-ld = {

};</syntaxhighlight>

<!--T:60-->

Log out and back in to apply the environment variables it sets, and you can then directly run the binary.

<!--T:61-->

If you don't want to configure the list of libraries manually, a quick and dirty way to run nearly any precompiled binary is the following:

<syntaxhighlight lang="nix">

programs.nix-ld = {

};</syntaxhighlight>

<!--T:63-->

This uses the libraries that are used by [[Steam]] to simulate a traditional Linux FHS environment to run games in. It's a [https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/st/steam/package.nix big list] that usually contains all the libraries your binary needs to run.

<!--T:64-->

Another possibility is to use [https://nixos.org/patchelf.html patchelf] to set the library path and dynamic linker appropriately, since compiled binaries have hard-coded interpreter and require certain dynamic libraries.

<syntaxhighlight lang="nix">

# mybinaryprogram.nix

   '';

}</syntaxhighlight>

This can be built with:

<!--T:66-->

And run with:

<!--T:67-->

Another possibility is using a FHS-compatible Sandbox with [https://nixos.org/nixpkgs/manual/#sec-fhs-environments buildFHSUserEnv]

<syntaxhighlight lang="nix">

# fhsUser.nix

   runScript = "bash";

}).env</syntaxhighlight>

the sandbox can be entered with

<!--T:10-->

If your target application can't find shared libraries inside buildFHSUserEnv, you may run [https://github.com/lexleogryfon/de-generate nix-de-generate] for target application inside FHS, which will generate newenv.nix file, an nix-expression of buildFHSUserEnv with resolved dependencies for shared libraries.

<!--T:136-->

=== What are channels and how do they get updated? ===

{{main|Channel branches}}

<!--T:69-->

[https://github.com/NixOS/nixpkgs 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.

* For nixos-small: the unstable-small [http://hydra.nixos.org/job/nixos/unstable-small/tested tested] job.

* For nixpkgs: the trunk [http://hydra.nixos.org/job/nixpkgs/trunk/unstable unstable] job, which contains some critical release packages.

<ol start="2" style="list-style-type: decimal;">

<!--T:77-->

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.

<!--T:79-->

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

<!--T:80-->

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

<!--T:12-->

=== Nixpkgs branches ===

Branches on the nixpkgs repo have a relationship with channels, but that relationship is not 1:1.

<!--T:84-->

You can jump the queue and use <code>nix-shell</code> with a <code>NIX_PATH</code> pointing to a tarball of the channel to get a shell for that software. Some building may occur. This will not work for system services.

<syntaxhighlight lang="command">

NIX_PATH=nixpkgs=https://github.com/NixOS/nixpkgs/archive/release-17.09.tar.gz nix-shell -p $software

</syntaxhighlight>

=== How do I install a specific version of a package for build reproducibility etc.? === <!--T:14-->

<!--T:91-->

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

<!--T:92-->

remount the filesystem with write privileges (as root)

<!--T:93-->

update the file

<!--T:94-->

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

<!--T:95-->

Be sure to [https://github.com/NixOS/nixpkgs/issues report the incorrect url] or [https://github.com/NixOS/nixpkgs/pulls fix it yourself].

<!--T:97-->

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

<syntaxhighlight lang="bash">nix-prefetch-git https://git.zx2c4.com/password-store</syntaxhighlight>

<!--T:99-->

Or, use <code>lib.fakeHash</code> as the fetcher's hash argument, and attempt to build; Nix will tell you the actual and expected hash's mismatch, and you may copy the actual hash.

<!--T:105-->

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

<syntaxhighlight lang="bash">nixos-rebuild switch --option binary-caches ''</syntaxhighlight>

=== How do I enable sandboxed builds on non-NixOS? === <!--T:20-->

<!--T:107-->

Two options have to be added to make sandboxed builds work on Nix, ''build-use-sandbox'' and ''build-sandbox-paths'':

<syntaxhighlight lang="nix">

# /etc/nix/nix.conf

build-sandbox-paths = $(nix-store -qR $(nix-build '<nixpkgs>' -A bash) | xargs echo /bin/sh=$(nix-build '<nixpkgs>' -A bash)/bin/bash)

</syntaxhighlight>

On NixOS set the following in ''configuration.nix'':

<syntaxhighlight lang="nix">

nix.settings.sandbox = true;

</syntaxhighlight>

<!--T:110-->

See [[Nix package manager#Sandbox_builds]] for more details.

<!--T:111-->

If you simply want to run a ''nix-shell'' with a package from unstable, you can run a command like the following:

<syntaxhighlight lang="bash">nix-shell -I nixpkgs=channel:nixpkgs-unstable -p somepackage</syntaxhighlight>

<!--T:113-->

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

<!--T:114-->

After updating the channel

<!--T:115-->

queries via <code>nix-env</code> 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''.

<syntaxhighlight lang="nix">

{ config, pkgs, ... }:

</syntaxhighlight>

<!--T:117-->

This only changes what version of <code>PACKAGE_NAME</code> is available on <code>$PATH</code>. If the package you want to take from unstable is installed through a NixOS module, you must use [[overlays]]:

<syntaxhighlight lang="nix">

{ config, pkgs, ... }:

}

</syntaxhighlight>

Note that this will rebuild all packages depending on the overlaid package, which may be a lot. Some modules offer a <code>services.foo.package</code> to change the actual derivation used by the module without and overlay, and without recompiling dependencies ([https://nixos.org/manual/nixos/stable/options.html#opt-services.gvfs.package example]).

<!--T:118-->

If you want to install unfree packages from unstable you need to also set allowUnfree by replacing the import statment above with:

<syntaxhighlight lang="nix">

import <nixos-unstable> { config = { allowUnfree = true; }; }

</syntaxhighlight>

=== I'm unable to connect my USB HDD | External HDD is failing to mount automatically === <!--T:22-->

<!--T:120-->

exfat is not supported in NixOS by default - since there are legality issues still with exFAT filesystem.  

<syntaxhighlight lang="bash">su nano /etc/nixos/configuration.nix</syntaxhighlight>

<!--T:122-->

Add this line to your configuration file.

<syntaxhighlight lang="bash">boot.extraModulePackages = [ config.boot.kernelPackages.exfat-nofuse ];</syntaxhighlight>

<!--T:123-->

After saving the file rebuild NixOS:

<syntaxhighlight lang="bash">nixos-rebuild switch</syntaxhighlight>

<!--T:125-->

Restart NixOS.

<!--T:127-->

=== What does it mean to say that NixOS is "immutable" ===

Immutability is a property of data, in general, which means that the data cannot be modified after it is created. In the context of an operating system, it really means that certain parts of the system have this property. In the case of Nix and NixOS, that includes the Nix store, where files can be created but not modified after the time they are created. It does not apply to every part of the operating system, in that users can still modify their own files in their home directory, for example.

<!--T:132-->

(Note that none of this applies to the [https://nix.dev/manual/nix/stable/language/builtins#builtins-import <code>import</code> built-in Nix language function], which is its own thing.)

{{:FAQ/Libraries}}

{{:FAQ/nix-env -iA}}

<!-- Transclude subpages -->

== References == <!--T:134-->