Man pages locate documentation by scanning directories listed in the MANPATH environment variable, which is distinct from the executable search path $PATH. To view manual pages for software installed in non-standard locations without modifying system-wide configuration files, you can explicitly set MANPATH to include your custom binary directories or use the -I flag with the man command.
Understanding the Difference Between $PATH and MANPATH
When you install experimental software, especially if you are compiling from source or using a local prefix like/usr/local or a user-specific directory such as $HOME/.local, the executables often end up in subdirectories like bin/ or sbin/. The shell finds these executables because they are appended to your $PATH variable. However, the man utility does not automatically derive its search paths from $PATH. It relies entirely on MANPATH.
If you do not configure MANPATH, the system will only look in standard directories such as /usr/share/man and /usr/local/man. If your new software places its man pages in a different structure, or if you have placed them alongside your binaries in a custom directory, typing man mytool will result in "No manual entry for mytool". This separation allows administrators to keep documentation organized separately from code, but it requires explicit configuration for non-standard installations.
Method 1: Using the -I Flag for Immediate Access
The quickest way to test if your man pages are accessible is to use the-I (include) option with the man command. This flag tells the man page viewer to add a specific directory to its search path for that single invocation. For example, if you installed a tool in /opt/myapp/bin and its documentation is in /opt/myapp/man, you would run:
man -I /opt/myapp/man mytool-I flags to search several directories at once, which is useful when testing software that has dependencies spread across different prefixes.
Method 2: Setting MANPATH Permanently
For a more permanent solution that mimics how$PATH handles executables, you should export the MANPATH variable in your shell profile. Common profile files include ~/.bashrc, ~/.zshrc, or /etc/profile depending on your system scope.
To append your custom directory to the existing man paths, avoid overwriting MANPATH completely, as this might remove access to system-wide documentation. Instead, use the following syntax in your profile:
export MANPATH="/path/to/custom/man:$MANPATH"source ~/.bashrc or open a new terminal session. Now, running man mytool will automatically check your custom directory first. If you want the system to automatically guess the man path based on the binary's location, you can also ensure that MANPATH contains the string :: (two colons), which instructs the man database to derive the path relative to the binary's directory, similar to how $PATH operates. However, this behavior varies by implementation, so explicit inclusion is often more reliable for experimental setups.
Verifying Your Configuration
Once you have configured your environment, it is crucial to verify that the changes took effect. You can check the current value ofMANPATH by echoing the variable:
echo $MANPATH-w flag to see exactly where man finds the documentation:
man -w mytoolmytool.1.gz for section 1).
Common Pitfalls with Experimental Software
Many experimental projects do not follow the Filesystem Hierarchy Standard (FHS). They might place man pages indocs/ or man/ inside the project root rather than a dedicated share/man directory. In these cases, you must point MANPATH to the parent directory of the section folders (e.g., /project/root/man) rather than the section folder itself.
Another common issue arises when using package managers like pip or npm with the --user flag. These tools often install binaries in $HOME/.local/bin but may not automatically update MANPATH. You may need to manually add $HOME/.local/share/man to your MANPATH variable to ensure those user-level packages are searchable.
For users managing complex development environments, consider looking into other technical configurations that enhance your workflow. You might find related utilities helpful, such as those discussed in Controlling Files with jdupes Hardlinks: A Guide for managing duplicate documentation files, or Setting Up Traefik for Reverse Proxy and Container Network on Tech Support Site if your experimental software involves web services.
Frequently Asked Questions
Why doesn't man find my tool even though it's in $PATH?
The man command does not read the $PATH variable to locate documentation; it exclusively uses MANPATH. Even if the shell can execute the binary, the manual viewer will fail unless the directory containing the man pages is explicitly added to MANPATH.
How do I reset MANPATH to default system values?
You can reset MANPATH by unsetting the variable with unset MANPATH in your terminal. Alternatively, running man --path often displays the compiled-in default paths used by the system when no user-defined MANPATH is present.
Can I use wildcards in MANPATH?
No, MANPATH expects explicit directory paths. Wildcards are not supported in the environment variable definition. If you have many custom directories, you must list them individually or use a script to generate the colon-separated string before exporting.
What if my man pages are compressed?
Modern versions of man automatically handle compressed files with extensions like .gz or .bz2. You do not need to decompress them manually. Ensure that the file name follows the standard convention, such as command.1.gz, so the parser can identify the section number correctly.
Is there a way to debug why man fails to find a page?
Yes, you can use the -d (debug) flag with man to see the internal logic it uses to search for files. Running man -d mytool will print detailed information about which directories were checked and why they were skipped, helping you pinpoint configuration errors.