Official NixOS Wiki

FAQ/en: Difference between revisions

← Older edit
FuzzyBot (talk | contribs)
2,910 edits
VisualWikitext
FuzzyBot (talk | contribs)
2,910 edits
Updating to match new version of source page
Tags: Mobile edit Mobile web edit
FuzzyBot (talk | contribs)
2,910 edits
Updating to match new version of source page
 
(One intermediate revision by the same user not shown)
Line 39: Line 39:
   };
   };
}</syntaxhighlight>
}</syntaxhighlight>
Check 'man configuration.nix' for these options. Rebuild for these options to take effect:
Check 'man configuration.nix' for these options. Rebuild for these options to take effect:


<syntaxhighlight lang="bash">nixos-rebuild switch</syntaxhighlight>
<syntaxhighlight lang="bash">nixos-rebuild switch</syntaxhighlight>
List all store paths that form the system closure and realise them:
List all store paths that form the system closure and realise them:


Line 50: Line 52:
<build output and list of successfully realised paths>
<build output and list of successfully realised paths>
</syntaxhighlight>
</syntaxhighlight>
Repeat for your user and further profiles:
Repeat for your user and further profiles:


<syntaxhighlight lang="bash">nix-store -qR ~/.nix-profile | xargs nix-store -r</syntaxhighlight>
<syntaxhighlight lang="bash">nix-store -qR ~/.nix-profile | xargs nix-store -r</syntaxhighlight>
The warning can be ignored for profiles that are listed/linked in ''/nix/var/nix/profiles/'' or one of its subdirectories.
The warning can be ignored for profiles that are listed/linked in ''/nix/var/nix/profiles/'' or one of its subdirectories.


Line 91: Line 95:
20  2014-08-12 19:09:20  (current)
20  2014-08-12 19:09:20  (current)
</syntaxhighlight>
</syntaxhighlight>
To rollback to the previous generation:
To rollback to the previous generation:


Line 97: Line 102:
switching from generation 20 to 19
switching from generation 20 to 19
</syntaxhighlight>
</syntaxhighlight>
To switch to a particular generation:
To switch to a particular generation:


Line 107: Line 113:


<syntaxhighlight lang="bash">nix-build -E 'with import <nixpkgs> { }; callPackage ./mypackage.nix { }'</syntaxhighlight>
<syntaxhighlight lang="bash">nix-build -E 'with import <nixpkgs> { }; callPackage ./mypackage.nix { }'</syntaxhighlight>
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.
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.


Line 122: Line 129:


<syntaxhighlight lang="bash">sudo nix-build --check -A ncdu</syntaxhighlight>
<syntaxhighlight lang="bash">sudo nix-build --check -A ncdu</syntaxhighlight>
=== How can I manage software with nix-env like with configuration.nix? ===
=== How can I manage software with nix-env like with configuration.nix? ===


Line 150: Line 158:


=== I've downloaded a binary, but I can't run it, what can I do? ===
=== 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.
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.


Line 198: Line 207:
   '';
   '';
}</syntaxhighlight>
}</syntaxhighlight>
This can be built with:
This can be built with:


<syntaxhighlight lang="bash">nix-build mybinaryprogram.nix</syntaxhighlight>
<syntaxhighlight lang="bash">nix-build mybinaryprogram.nix</syntaxhighlight>
And run with:
And run with:


<syntaxhighlight lang="bash">./result/bin/mybinaryprogram</syntaxhighlight>
<syntaxhighlight lang="bash">./result/bin/mybinaryprogram</syntaxhighlight>
Another possibility is using a FHS-compatible Sandbox with [https://nixos.org/nixpkgs/manual/#sec-fhs-environments buildFHSUserEnv]
Another possibility is using a FHS-compatible Sandbox with [https://nixos.org/nixpkgs/manual/#sec-fhs-environments buildFHSUserEnv]


Line 227: Line 239:
   runScript = "bash";
   runScript = "bash";
}).env</syntaxhighlight>
}).env</syntaxhighlight>
the sandbox can be entered with
the sandbox can be entered with


<syntaxhighlight lang="bash">nix-shell fhsUser.nix</syntaxhighlight>
<syntaxhighlight lang="bash">nix-shell fhsUser.nix</syntaxhighlight>
<br>
 
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.
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.


=== What are channels and how do they get updated? ===
=== What are channels and how do they get updated? ===
{{main|Channel branches}}
{{main|Channel branches}}


Line 261: Line 275:
* For nixos-small: the unstable-small [http://hydra.nixos.org/job/nixos/unstable-small/tested tested] job.
* 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.
* 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;">
<ol start="2" style="list-style-type: decimal;">
<li>Once the job succeeds at a particular nixpkgs commit, '''cache.nixos.org''' will download binaries from '''hydra.nixos.org'''.</li>
<li>Once the job succeeds at a particular nixpkgs commit, '''cache.nixos.org''' will download binaries from '''hydra.nixos.org'''.</li>
<li>Once the above download completes, the channel updates.</li></ol>
<li>Once the above download completes, the channel updates.</li>
</ol>


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.
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.
Line 275: Line 291:


<syntaxhighlight lang="bash">nix-instantiate --find-file nixpkgs</syntaxhighlight>
<syntaxhighlight lang="bash">nix-instantiate --find-file nixpkgs</syntaxhighlight>
To know the commit, open the .version-suffix file in the nixpkgs location. The hash after the dot is the git commit.
To know the commit, open the .version-suffix file in the nixpkgs location. The hash after the dot is the git commit.


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


Line 293: Line 311:
<syntaxhighlight lang="command">
<syntaxhighlight lang="command">
NIX_PATH=nixpkgs=https://github.com/NixOS/nixpkgs/archive/release-17.09.tar.gz nix-shell -p $software
NIX_PATH=nixpkgs=https://github.com/NixOS/nixpkgs/archive/release-17.09.tar.gz nix-shell -p $software
</syntaxhighlight>
=== There's an updated version for $software on the unstable branch, but I use stable, how can I use it? ===
Before going ahead with this, note that firstly, this likely means that the package you intend to update has had a major version change. If you have used it previously, there is a chance that your existing data either will not work with the new version or will need to be migrated; If in doubt, consult the upstream documentation of the package.
Secondly, while you're less likely to run into issues on NixOS than on, for example, Debian when installing packages from different releases, it's not impossible.
Nix ensures that libraries and (usually) runtime dependencies of packages are kept separate, so that you can trivially have many versions of those dependencies installed, without affecting the versions of said dependencies used by important system components. This ensures that you cannot accidentally break your package manager by, say, updating Python, as is quite common on other distros.
Nix cannot however ensure that there will be no incompatibilities with services of which there can inherently be only one running instance. As an example, if you try to use a package from unstable on a stable system that requires a feature in systemd that is not yet present in the systemd version on stable, this package will not work; it's simply not possible to run two different versions of systemd simultaneously.
Nonetheless, it's quite uncommon that end-user facing applications rely on such singleton services, or at the very least they will typically have internal backwards compatibility. As such, mixing channels is usually unproblematic in practice, and even if not, NixOS' rollback features make it trivial to recover from problems should they occur.
==== Using channels ====
First we need to add the unstable channel to our system channels:
{{Warning|`nixos-rebuild --upgrade` will by default only update the channel named `nixos`, which this new channel is not. Use `nixos-rebuild --upgrade-all` instead.}}
<syntaxhighlight lang="console">
$ sudo nix-channel --add https://nixos.org/channels/nixos-unstable nixos-unstable
$ sudo nix-channel --update
</syntaxhighlight>
Then we can import this channel using the angle-bracket notation to refer to it:
<syntaxhighlight lang="nixos"># configuration.nix
{
  config,
  pkgsUnstable,
  ...
}: {
  # We add a new `pkgsUnstable` to the module arguments; this allows
  # us to easily use `pkgsUnstable` in other modules as well, without
  # having to evaluate it again.
  _module.args.pkgsUnstable = import <nixos-unstable> { inherit (config.nixpkgs) config; };
  environment.systemPackages = [
    # Once we have created our `pkgsUnstable`, we can easily use
    # packages from it wherever NixOS modules expect derivations
    pkgsUnstable.hello
  ];
}</syntaxhighlight>
==== Using flakes ====
We simply add the unstable branch to our flake inputs, and pass them into the NixOS module system using <code>specialArgs</code>:
<syntaxhighlight lang="nix">
# flake.nix
{
  inputs = {
    nixpkgs.url = "https://channels.nixos.org/nixos-25.05/nixexprs.tar.xz";
    nixpkgs-unstable.url = "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz";
  };
  outputs = { nixpkgs, ... } @ inputs: {
    # Note that the hostname "nixos" and the system tuple used here are
    # examples.
    nixosConfigurations."nixos" = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
      ];
      # Any attributes of `specialArgs` will be added to our NixOS module
      # arguments.
      #
      # We've bound `nixpkgs-unstable` to the `inputs` variable using the `@`
      # syntax; if we add any other flake inputs in the future those will also
      # be added to our module arguments.
      specialArgs.flake-inputs = inputs;
    };
  };
}
</syntaxhighlight>
Using this in <code>configuration.nix</code> then looks as follows:
<syntaxhighlight lang="nixos">
# configuration.nix
{
  pkgs,
  flake-inputs,
  ...
}: {
  environment.systemPackages = [
    flake-inputs.nixpkgs-unstable.legacyPackages.${pkgs.system}.hello
  ];
}
</syntaxhighlight>
</syntaxhighlight>


Line 312: Line 422:


<syntaxhighlight lang="bash">sudo unshare -m bash</syntaxhighlight>
<syntaxhighlight lang="bash">sudo unshare -m bash</syntaxhighlight>
remount the filesystem with write privileges (as root)
remount the filesystem with write privileges (as root)


<syntaxhighlight lang="bash">mount -o remount,rw /nix/store</syntaxhighlight>
<syntaxhighlight lang="bash">mount -o remount,rw /nix/store</syntaxhighlight>
update the file
update the file


<syntaxhighlight lang="bash">nano <PATH_TO_PACKAGE>/default.nix</syntaxhighlight>
<syntaxhighlight lang="bash">nano <PATH_TO_PACKAGE>/default.nix</syntaxhighlight>
exit to shell where /nix/store is still mounted read-only
exit to shell where /nix/store is still mounted read-only


<syntaxhighlight lang="bash">exit</syntaxhighlight>
<syntaxhighlight lang="bash">exit</syntaxhighlight>
Be sure to [https://github.com/NixOS/nixpkgs/issues report the incorrect url] or [https://github.com/NixOS/nixpkgs/pulls fix it yourself].
Be sure to [https://github.com/NixOS/nixpkgs/issues report the incorrect url] or [https://github.com/NixOS/nixpkgs/pulls fix it yourself].


Line 362: Line 476:
build-sandbox-paths = $(nix-store -qR $(nix-build '<nixpkgs>' -A bash) | xargs echo /bin/sh=$(nix-build '<nixpkgs>' -A bash)/bin/bash)
build-sandbox-paths = $(nix-store -qR $(nix-build '<nixpkgs>' -A bash) | xargs echo /bin/sh=$(nix-build '<nixpkgs>' -A bash)/bin/bash)
</syntaxhighlight>
</syntaxhighlight>
On NixOS set the following in ''configuration.nix'':
On NixOS set the following in ''configuration.nix'':


Line 379: Line 494:


<syntaxhighlight lang="bash">sudo nix-channel --add https://nixos.org/channels/nixos-unstable nixos-unstable</syntaxhighlight>
<syntaxhighlight lang="bash">sudo nix-channel --add https://nixos.org/channels/nixos-unstable nixos-unstable</syntaxhighlight>
After updating the channel
After updating the channel


<syntaxhighlight lang="bash">sudo nix-channel --update nixos-unstable</syntaxhighlight>
<syntaxhighlight lang="bash">sudo nix-channel --update nixos-unstable</syntaxhighlight>
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''.
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''.


Line 394: Line 511:


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]]:
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">
<syntaxhighlight lang="nix">
{ config, pkgs, ... }:
{ config, pkgs, ... }:
Line 406: Line 524:
}
}
</syntaxhighlight>
</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]).
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]).


If you want to install unfree packages from unstable you need to also set allowUnfree by replacing the import statment above with:
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">
<syntaxhighlight lang="nix">
import <nixos-unstable> { config = { allowUnfree = true; }; }
import <nixos-unstable> { config = { allowUnfree = true; }; }
Line 422: Line 542:


Add this line to your configuration file.
Add this line to your configuration file.
<syntaxhighlight lang="bash">boot.extraModulePackages = [ config.boot.kernelPackages.exfat-nofuse ];</syntaxhighlight>
<syntaxhighlight lang="bash">boot.extraModulePackages = [ config.boot.kernelPackages.exfat-nofuse ];</syntaxhighlight>


Line 435: Line 556:


=== What does it mean to say that NixOS is "immutable" ===
=== 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.
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.


Retrieved from "https://wiki.nixos.org/wiki/FAQ/en"