From 39f064f0e36717c414bba74e9820f66b8acd6611 Mon Sep 17 00:00:00 2001 From: Aliaksandr Date: Sat, 9 May 2026 17:49:31 +0300 Subject: [PATCH] doc/using/configuration: document NIXPKGS_CONFIG lookup order The NIXPKGS_CONFIG environment variable and the system-wide /etc/nix/nixpkgs-config.nix path used by NixOS were undocumented in the Nixpkgs manual; the only mention was a release-note from 2006. Add a short paragraph to the Global configuration chapter describing the lookup order, the NixOS-specific default, and the limitation that the file is not generated automatically. Closes #28085. --- doc/using/configuration.chapter.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/using/configuration.chapter.md b/doc/using/configuration.chapter.md index 5934726c068b..c54124fbe7a6 100644 --- a/doc/using/configuration.chapter.md +++ b/doc/using/configuration.chapter.md @@ -31,6 +31,22 @@ Unfree software is not tested or built in Nixpkgs continuous integration, and th Most unfree licenses prohibit either executing or distributing the software. ::: +The `NIXPKGS_CONFIG` environment variable can override the configuration file location. +Nixpkgs resolves the config in this order: + +1. `$NIXPKGS_CONFIG`, if set and the file exists. +2. `~/.config/nixpkgs/config.nix`, if it exists. +3. `~/.nixpkgs/config.nix` (legacy), if it exists. +4. Empty configuration. + +On NixOS, `NIXPKGS_CONFIG` points to `/etc/nix/nixpkgs-config.nix` system-wide. +Drop a file there to apply configuration to `nix-env`, `nix-shell`, and other user-level commands. +NixOS does not create this file. +The [`nixpkgs.config`](https://nixos.org/manual/nixos/stable/options#opt-nixpkgs.config) option does not affect `nix-env`, `nix-shell`, or other user-level commands. + +This lookup applies to non-flake usage like channels and ``. +Flakes ignore it; pass `config` directly when importing `nixpkgs`. + ## Installing broken packages {#sec-allow-broken} There are several ways to try compiling a package which has been marked as broken.