1 files changed, 26 insertions, 4 deletions
diff --git a/nixos/doc/manual/configuration/customizing-packages.section.md b/nixos/doc/manual/configuration/customizing-packages.section.md
index a524ef266eaf..074932b3f110 100644
--- a/nixos/doc/manual/configuration/customizing-packages.section.md
+++ b/nixos/doc/manual/configuration/customizing-packages.section.md
@@ -1,11 +1,33 @@
 # Customising Packages {#sec-customising-packages}
 
-Some packages in Nixpkgs have options to enable or disable optional
-functionality or change other aspects of the package.
+The Nixpkgs configuration for a NixOS system is set by the {option}`nixpkgs.config` option.
+
+::::{.example}
+# Globally allow unfree packages
+
+```nix
+{
+  nixpkgs.config = {
+    allowUnfree = true;
+  };
+}
+```
+
+:::{.note}
+This only allows unfree software in the given NixOS configuration.
+For users invoking Nix commands such as [`nix-build`](https://nixos.org/manual/nix/stable/command-ref/nix-build), Nixpkgs is configured independently.
+See the [Nixpkgs manual section on global configuration](https://nixos.org/manual/nixpkgs/unstable/#chap-packageconfig) for details.
+:::
+::::
+
+<!-- TODO(@fricklerhandwerk)
+all of the following should go to the Nixpkgs manual, it has nothing to do with NixOS
+-->
+
+Some packages in Nixpkgs have options to enable or disable optional functionality, or change other aspects of the package.
 
 ::: {.warning}
-Unfortunately, Nixpkgs currently lacks a way to query available
-configuration options.
+Unfortunately, Nixpkgs currently lacks a way to query available package configuration options.
 :::
 
 ::: {.note}