Trace and Fix a Manual Page Search Path with manpath

A familiar command suddenly opens the wrong manual page, and manpath shows you exactly which directories man is searching and why. This guide covers the calculated default path, testing a temporary MANPATH, and finding which part of /etc/manpath.config supplies the result. Examples use manpath 2.12.0 from man-db 2.12.0-4build2. 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 needs elevated privileges and is deliberately left for the last, diagnostic step.

1. Record the installed version

Start with 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 your distribution. Keep it with your notes, since distribution patches and config files can change the result even when the upstream man-db version matches.

2. See the automatically generated path

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

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

Your directories will differ. With no MANPATH set, man-db examines PATH, applies any MANPATH_MAP mappings from /etc/manpath.config, adds existing conventional manual directories, then appends 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 entry is a directory holding section directories such as man1 or man5; a path can be present even when a specific page is not.

3. Check whether MANPATH is taking over

An existing MANPATH changes the question entirely. manpath prints that value unchanged and warns that the config 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 goes to standard error, so a terminal or log collector may show the two streams in a different order. The key result is that the two directories come back unchanged. If a page goes missing after setting MANPATH, check this variable before editing system configuration.

For a one-off test, set it only on the command you are checking:

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

This does not touch your shell's environment afterwards. The example fails because the placeholder directory holds no page; swap in a real directory when testing an actual local tree.

4. Add the default path back in deliberately

man-db treats an empty field in MANPATH as a placeholder for its calculated default. A leading colon puts the default first, a trailing colon puts it last, and a double colon inserts it between two 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 the fix for a wrapper or shell session that needs one private manual tree without losing system documentation. A common trap is setting MANPATH to a single directory and then wondering why every distribution page vanished; use an empty field to mean "my directory plus the normal path".

5. Compare global and cat paths

--global asks for the paths the configuration marks as global:

$ 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 proof every directory exists. It is useful when a page works for one account but not another, or when checking whether an installed manual tree made it into the system map.

--catpath shows the matching locations for preformatted cat pages instead:

$ 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 cache destinations chosen by MANDB_MAP entries, not source manual trees, so a read-only manual tree can still have a writable cache elsewhere.

6. Include another operating system's pages

If a manual tree has a system-specific subdirectory, --systems can add it. The name man means the native path, and you need it explicitly if you still want native pages alongside 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

Only swap man for another system name after confirming the matching subdirectories actually exist below a search-path entry. The option overrides SYSTEM from the environment; include man explicitly in a comma or colon-separated list when native pages must stay available.

7. Inspect configuration before changing it

Read the relevant directives first, without editing anything:

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

• MANDATORY_MANPATH adds directories to the automatically generated path.
• MANPATH_MAP connects a PATH binary directory to its manual directory.
• MANDB_MAP marks system trees and can pick their cat cache. Order matters here: a more specific tree must come 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. Check MANPATH first, then confirm the manual directory exists and holds the expected section, for example ls /opt/example/share/man/man1. Only an administrator should change the system file, and a backup is your recovery point:

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

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