Rebuild the Manual Page Index with mandb

man suddenly cannot find a page you know is installed, and mandb fixes that by rebuilding the index behind man, whatis and friends. This guide covers testing, updating and rebuilding those databases. Examples use man-db 2.12.0, package version 2.12.0-4build2. Allow fifteen minutes for a normal update, longer on a host with large manual trees.

You need a shell and an installed man-db package. Reading the configuration and running a test needs no elevated privilege. Updating the system cache usually does, since this host maps /usr/share/man to /var/cache/man. Use sudo only for that cache update, and only after you have checked the paths.

1. Check the command and its search path

Start with read-only checks. This confirms which executable and version you have, and which manual hierarchies are in scope:

$ command -v mandb
/usr/bin/mandb
$ mandb --version
mandb 2.12.0
$ manpath
/usr/local/man:/usr/local/share/man:/usr/share/man:/usr/share/man/en

Your own manpath output may differ. The config lives at /etc/manpath.config; on this machine it maps the global /usr/share/man hierarchy to /var/cache/man. Do not assume every directory listed in MANPATH shares that same cache location.

Checkpoint: if command -v mandb is empty, install man-db through your normal package-management process. Do not copy a binary from another host just to get the next command running.

2. Test the manual pages without touching the databases

--test, or -t, does a correctness pass. It checks pages across the hierarchy search path and leaves existing databases untouched:

$ mandb --test
mandb: warning: /path/to/page.7: whatis parse for page(7) failed
mandb: warning: /path/to/old-link.1: is a dangling symlink

• Warnings are findings, not failures. A whatis parse warning usually means a page's description could not be extracted.
• A dangling symlink or a bad ROFF .so request points to a broken reference worth tracking down.
• An invalid filename can be ignored. Note the affected path and check the package or local file that owns it before changing anything.

Output is host-specific, and a clean run can produce none at all. Check the exit status if a script needs to tell success from failure:

$ mandb --test
$ printf 'mandb test status: %s\n' "$?"
mandb test status: 0

3. Update the normal system indexes

Once the test result looks reasonable, run the ordinary update against the configured manual path. It updates existing databases, creates missing ones, and purges entries for pages that no longer exist:

$ sudo mandb
Processing manual pages under /usr/share/man...
...done.

Exact progress text depends on the build and page count. A successful run exits 0, and it can print warnings while still completing fine. This changes the cache, not the manual source files: it does not install new manuals, repair a broken page, or create compressed cat pages. Confirm a page is indexed afterwards with a read-only query:

$ whatis mandb
mandb (8) - create or update the manual page index caches

4. Rebuild a damaged cache from scratch

--create, or -c, deletes the previous database and rebuilds it, so treat it as a state-changing operation for a suspected-corrupt index or a changed storage scheme:

$ sudo mandb --create
Processing manual pages under /usr/share/man...
...done.

Warning: do not run -c as a reflex after every package install. The plain update is the less disruptive choice. -c also implies --no-purge, so it skips checking for deleted pages during that rebuild. If it fails, fix the reported path or permission problem and rerun the ordinary update; there is no separate rollback command.

5. Reach for narrow options only for narrow problems

• -p or --no-purge skips checking for deleted manual pages. Useful during a controlled update, but stale entries can linger.
• -s or --no-straycats skips looking for stray cat-page information, not manual page sources.
• -u or --user-db creates user databases only, even when the process could write system ones. Handy for a private manual hierarchy, and it normally avoids sudo entirely.
• -q or --quiet suppresses warnings. Only use it when another diagnostic path records failures; hiding warnings makes real manual-page defects harder to spot.

For a private hierarchy, pass its colon-delimited path explicitly:

$ test -d "$HOME/.local/share/man" && echo 'private manual path exists'
$ mandb --user-db "$HOME/.local/share/man"

The user config file can be chosen with -C FILE; the default is ~/.manpath. Do not point it at /etc/manpath.config unless you have confirmed the file format and purpose actually match.

6. Update one page only when you know why

-f or --filename updates entries for named files. The man page describes this as an internal mode man itself uses when built with MAN_DB_UPDATES, not the normal administrator workflow:

$ sudo mandb --filename /usr/share/man/man8/mandb.8.gz

Use the full, existing filename and check its path first. This mode implies --no-purge and disables --create and --no-straycats. For a routine package update, run plain mandb instead so the whole hierarchy gets considered.

7. Read status codes before touching permissions

Use the exit status in automation rather than treating any stderr text as fatal:

If a system update reports permission errors, inspect the configured mapping before adding privileges:

$ grep -E '^(MANDB_MAP|MANDATORY_MANPATH)' /etc/manpath.config
$ ls -ld /var/cache/man /usr/share/man

Warning: do not delete files from /var/cache/man while troubleshooting. Preserve the warning or error first, confirm package ownership, and check whether another process is updating the cache. If the database really is corrupt, the documented recovery is sudo mandb --create, once the underlying permissions or filesystem problem is understood.

Done means

• Installed man-db version and search path confirmed.
• mandb --test completed before any cache update.
• sudo used only for the configured global cache.
• Warnings reviewed, not hidden behind --quiet.
• --create used only for a known cache-rebuild problem.
• whatis or another read-only query finds the page you needed.