Trace and Fix a Linux Manual Page Search Path with manpath

You will finish with a reliable way to see where Linux is looking for manual pages, test a temporary MANPATH value, and understand which part of /etc/manpath.config supplies the result. The examples use manpath 2.12.0 from package man-db 2.12.0-4build2, as installed on this machine.

Allow about ten minutes. You need a shell and the man-db utilities. The main workflow only reads configuration and environment. Editing /etc/manpath.config requires elevated privileges and is deliberately left until the final diagnostic step.

1. Record the installed version

Start by confirming which command and package you are using. These are ordinary, read-only commands:

$ command -v manpath
/usr/bin/manpath
$ manpath --version
manpath 2.12.0
$ dpkg-query -W -f='${Package} ${Version}\n' man-db
man-db 2.12.0-4build2

The exact package suffix depends on the distribution. Keep it with your diagnostic notes because distribution patches and configuration files can change the result even when the upstream man-db version is the same.

Checkpoint: if command -v manpath prints nothing, install the distribution's man-db package through its normal package-management process before continuing. Do not copy a binary from an unrelated host.

2. See the automatically generated path

Clear only the two variables that affect the examples, then ask manpath for its normal result:

$ env -u MANPATH -u SYSTEM manpath
/home/linuxbrew/.linuxbrew/share/man:/usr/local/man:/usr/local/share/man:/usr/share/man

Your directories may differ. With no MANPATH, man-db examines PATH, applies any MANPATH_MAP mappings it finds in /etc/manpath.config, adds existing conventional manual directories, and then adds MANDATORY_MANPATH entries. The output is a colon-separated list, in search order.

Do not read the printed path as a list of files. Each item is a directory containing section directories such as man1 or man5. A path can be present even when a particular page is not.

3. Check whether MANPATH is taking over

An existing MANPATH changes the question. manpath prints its value instead of calculating a new path, and warns that the configuration file is being ignored:

$ MANPATH=/tmp/example-man:/opt/example/share/man manpath
/tmp/example-man:/opt/example/share/man
manpath: warning: $MANPATH set, ignoring /etc/manpath.config

The warning is written to standard error, so a terminal or log collector may display the two streams in a different order. The key result is that the two directories are returned unchanged. If a page is missing after you set MANPATH, inspect this variable before editing system configuration.

For a temporary test, set it only on the command you are testing:

$ MANPATH=/tmp/example-man man -w manpath
manpath: No manual entry for manpath

This does not modify your shell's environment after the command exits. The example reports a failure because the placeholder directory contains no page. Replace it with a real directory when testing a local manual tree.

4. Add the default path deliberately

man-db supports empty fields in MANPATH as a placeholder for its calculated default. A leading colon places the default first, a trailing colon places it last, and a double colon inserts it between the surrounding entries:

$ MANPATH=/tmp/example-man::/opt/example/share/man env -u SYSTEM manpath
/tmp/example-man:/home/linuxbrew/.linuxbrew/share/man:/usr/local/man:/usr/local/share/man:/usr/share/man:/opt/example/share/man

This is useful for a wrapper or a shell session that needs one private manual tree without losing system documentation. A common trap is setting MANPATH to one directory and then wondering why distribution pages disappeared. Use an empty field when you mean 'my directory plus the normal path'.

Checkpoint: run env | grep '^MANPATH='. If the variable is exported by a shell startup file, remove or correct that line there rather than repeatedly overriding it at the prompt.

5. Compare global and cat paths

Use --global to ask for paths marked as global by the configuration:

$ env -u MANPATH -u SYSTEM manpath --global
/usr/man:/usr/share/man:/usr/local/man:/usr/local/share/man:/usr/X11R6/man:/opt/man:/snap/man

This is a configuration view, not a promise that every directory exists. It is useful when a page works for one account but not another, or when checking whether an installed manual tree was included in the system map.

--catpath shows the corresponding locations for preformatted 'cat' pages:

$ env -u MANPATH -u SYSTEM manpath --catpath
/home/linuxbrew/.linuxbrew/share/man:/var/cache/man/oldlocal:/var/cache/man/local:/var/cache/man

Cat paths are not the source manual trees. They are cache destinations selected through MANDB_MAP entries. A read-only manual tree can therefore have a writable cache elsewhere.

6. Include another operating system's pages

If a manual tree contains a system-specific subdirectory, --systems can add it. The name man means the native path; it is needed when you want native pages as well as another system:

$ env -u MANPATH -u SYSTEM manpath --systems=man
/home/linuxbrew/.linuxbrew/share/man:/usr/local/man:/usr/local/share/man:/usr/share/man

Replace man with a system name only after checking that the corresponding subdirectories exist below a search-path entry. The option overrides SYSTEM from the environment. If you use a comma or colon-separated list, include man explicitly when native pages must remain available.

7. Inspect configuration before making a change

Read the relevant directives without editing them:

$ grep -E '^(MANDATORY_MANPATH|MANPATH_MAP|MANDB_MAP|SECTION)' /etc/manpath.config

MANDATORY_MANPATH adds directories to automatically generated paths. MANPATH_MAP connects a binary directory in PATH to its manual directory. MANDB_MAP marks system trees and can choose their cat cache. The order matters: a more specific tree must be listed before a parent tree, or man-db can match the parent first.

Do not edit this file as a first response to a missing page. First check MANPATH, then check that the manual directory exists and contains the expected section, for example ls /opt/example/share/man/man1. Only an administrator should change the system file, and a backup is the recovery point:

$ sudo cp -p /etc/manpath.config /etc/manpath.config.before-manpath-change
$ sudoedit /etc/manpath.config
$ env -u MANPATH -u SYSTEM manpath

Editing configuration is a persistent system change. If the result is wrong, restore the backup and rerun the final command:

$ sudo cp -p /etc/manpath.config.before-manpath-change /etc/manpath.config
$ env -u MANPATH -u SYSTEM manpath