From f4f9faa5641ef92303fd67ab9351452181d526ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20Ha=CC=88cker?= <spamfaenger@gmx.de>
Date: Fri, 30 Jan 2026 16:22:12 +0100
Subject: [PATCH] nixos/misc/nixpkgs: add documentation for
 nixpkgs.config.allowUnfreePackages

---
 doc/using/configuration.chapter.md | 51 +++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 15 deletions(-)

diff --git a/doc/using/configuration.chapter.md b/doc/using/configuration.chapter.md
index 98f5d76250d9..7317b5b198fd 100644
--- a/doc/using/configuration.chapter.md
+++ b/doc/using/configuration.chapter.md
@@ -105,27 +105,48 @@ There are several ways to tweak how Nix handles a package which has been marked
     $ export NIXPKGS_ALLOW_UNFREE=1
     ```
 
--   It is possible to permanently allow individual unfree packages, while still blocking unfree packages by default using the `allowUnfreePredicate` configuration option in the user configuration file.
-
-    This option is a function which accepts a package as a parameter, and returns a boolean. The following example configuration accepts a package and always returns false:
-
-    ```nix
-    { allowUnfreePredicate = (pkg: false); }
-    ```
-
-    For a more useful example, try the following. This configuration only allows unfree packages named roon-server and Visual Studio Code:
+-   To allow specific unfree packages, add their names to your Nixpkgs configuration file:
 
     ```nix
     {
-      allowUnfreePredicate =
-        pkg:
-        builtins.elem (lib.getName pkg) [
-          "roon-server"
-          "vscode"
-        ];
+      allowUnfreePackages = [
+        "fence"
+        "roon-server"
+        "vscode"
+      ];
     }
     ```
 
+    `allowUnfreePackages` permits the listed unfree packages.
+
+    In NixOS modules, lists set through `nixpkgs.config.allowUnfreePackages` merge additively across modules. This allows you to declare your unfree exceptions in the same modules that triggered them.
+
+    To allow unfree packages programmatically:
+
+    ```nix
+    { lib, ... }:
+    {
+      allowUnfreePredicate = pkg: lib.hasPrefix "roon" (lib.getName pkg);
+    }
+    ```
+
+    This permits packages such as `roon-bridge` and `roon-server`.
+
+    To combine the list and predicate, set both options:
+
+    ```nix
+    { lib, ... }:
+    {
+      allowUnfreePackages = [
+        "fence"
+        "vscode"
+      ];
+      allowUnfreePredicate = pkg: lib.hasPrefix "roon" (lib.getName pkg);
+    }
+    ```
+
+    This permits unfree packages that match either option.
+
 -   It is also possible to allow and block licenses that are specifically acceptable or not acceptable, using `allowlistedLicenses` and `blocklistedLicenses`, respectively.
 
     The following example configuration allowlists the licenses `amd` and `wtfpl`: