Apropos: Difference between revisions

Revision as of 18:16, 2 April 2026

By default as of NixOS 21.05, apropos, whatis and man -k do not find anything when run, because the man page index cache is not generated.

To build the cache automatically, you can set this in your system configuration:

{
  documentation.man.cache.enable = true;
}

Or in older versions:

{
  documentation.man.generateCaches = true;
}

This will create an immutable cache in sync with environment.systemPackages. Note that it will not be populated with programs from home-manager. Since it is immutable, the mandb command (see below) will fail.

Some programs might set this option to true by default. For example, this is the case of fish, which uses it to automatically create completions (see [fish_update_completions](https://fishshell.com/docs/current/cmds/fish_update_completions.html)).

To generate it manually, run:

$ sudo mkdir -p /var/cache/man/nixos
$ sudo mandb

This will need to be re-run to update the cache when new software is installed.

@@ Line 1: / Line 1: @@
 By default as of NixOS 21.05, <code>apropos</code>, <code>whatis</code> and <code>man -k</code> do not find anything when run, because the man page index cache is not generated.
-To generate it manually (and again to update it when new software is installed), run:
+To build the cache automatically, you can set this in your system configuration:
-<syntaxhighlight lang="console">
+<syntaxhighlight lang="nix">
-$ sudo mkdir -p /var/cache/man/nixos
+{
-$ sudo mandb
+  documentation.man.cache.enable = true;
+}
 </syntaxhighlight>
+Or in older versions:
-To enable automatically building the immutable cache, you can set in your system configuration:
 <syntaxhighlight lang="nix">
 {
@@ Line 13: / Line 13: @@
 }
 </syntaxhighlight>
-Note that this will rebuild the cache every time you change anything in <code>environment.systemPackages</code>, and will make the <code>mandb</code> command fail.
+This will create an immutable cache in sync with <code>environment.systemPackages</code>. Note that it will not be populated with programs from home-manager. Since it is immutable, the <code>mandb</code> command (see below) will fail.
+Some programs might set this option to true by default. For example, this is the case of [[fish]], which uses it to automatically create completions (see [fish_update_completions](https://fishshell.com/docs/current/cmds/fish_update_completions.html)).
+To generate it manually, run:
+<syntaxhighlight lang="console">
+$ sudo mkdir -p /var/cache/man/nixos
+$ sudo mandb
+</syntaxhighlight>
+This will need to be re-run to update the cache when new software is installed.
 [[Category:Configuration]]