Translations:FAQ/133/en
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 (or openssl, sqlite etc.) and uses pkg-config to discover it, run
$ nix-shell -p gcc pkg-config zlib
to get into a shell with the appropriate environment variables set. In there, a configure script (with C Autotools, C++ CMake, Rust Cargo etc.) 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.
Note that software built in such a shell may stop working after a garbage collection. This is because Nix only tracks dependencies of paths within the store. A clean build in a fresh shell can fix this one-off, but the long-term solution is to package the software in question rather than using a shell build regularly.
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 = [ pkg-config 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.
Why not use nix-env -i hello?
nix-env -i hello is slower and tends to be less precise than nix-env -f '<nixpkgs>' -iA hello. This is because it will evaluate all of nixpkgs searching for packages with the name hello, and install the one determined to be the latest (which may not even be the one that you want). Meanwhile, with -A, nix-env will evaluate only the given attribute in nixpkgs. This will be significantly faster, consume significantly less memory, and more likely get you what you want.
nix-env -u has the same problem, searching for all the packages in the user environment by name and upgrading them. This may lead to unwanted major-version upgrades like JDK 8 → JDK 9. If you want to have a declarative user environment, you may wish to use Home Manager. It is also possible to home-bake a pure nix solution like LnL's. With this setup, you can update your packages by simply running nix-rebuild.
<onlyinclude>
system.stateVersion should never be updatedWhy am I told not to update[1] system.stateVersion?
Since it is not clearly codified what system.stateVersion should be used for, and it is used for a great many different things in practice[2], there is no practical way to ensure that changing it is ever safe.
The consequences of changing its value range from none at all, to complete destruction of data written by specific software.
How do I update NixOS, if changing system.stateVersion does not do that?
See Updating nixos.
Why does system.stateVersion look like a NixOS version?
This is because it notes down the version of NixOS you first installed with a given configuration. It does not mean that you should update it.
When can I update system.stateVersion safely?
Currently, you cannot update it safely without a complete understanding of all NixOS modules you are using, directly or indirectly.
Only when the NixOS release notes say that it can be changed, should it be changed.
Is it ok to leave system.stateVersion at a very old version?
The NixOS module authors are aware of their use of the setting, and must ensure that old versions continue to work. Whether and how this is sustainable is an upstream issue; Users should not update the setting unless instructed otherwise.
What even is system.stateVersion for, if it is just an unchanging string?
Generally, it is used to inform NixOS what versions of packages you might have previously installed. This is used to ensure correct data migration for certain packages[1]. Since NixOS configurations are stateless, and therefore cannot know what data may already be on your system, there is no other way to identify this.
system.stateVersion in practice is also used for other potential issues that stem from version upgrades[2] - it is somewhat controversial what and what not it should be used for, resulting in many different use cases. The current and historic lack of a clear definition of what it does is part of why it cannot be updated.
References
</noinclude>
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; see Unfree software for more information
- the package is part of an attribute set and
nix-envdoesn't recurse into this set (see pkgs.recurseIntoAttrs), usenix-env -qaP -A haskellPackagesfor listing these entries
Unfree software refers to software that has restrictive licensing on modification and/or redistribution. This type of software cannot be freely provided or distributed in an official capacity, which means that unfree software is neither built by Hydra, nor cached on the official binary cache. Despite this, Nixpkgs offers a very large collection of unfree software as derivations, however they cannot be used by default without configuring Nixpkgs and opting in to unfree software usage.
Allowing unfree software
By default, nix will refuse to evaluate any derivation containing unfree software, prompting the user to read the manual for more details. This behaviour can be configured in different ways depending on the context of the derivation.
Unfree software using Home Manager
Depending on your Home Manager installation, there are multiple ways to allow unfree software.
Standalone Home Manager
If your Home Manager configuration isn't integrated into your NixOS configuration (i.e. you switch generations using home-manager switch and not by rebuilding the whole system), then you may allow unfree software by setting the nixpkgs option in your config:
{ ... }:
{
...
nixpkgs.config.allowUnfree = true;
}