How do I manually install a man page file?

Question

How do I install a man page file system-wide?

For example, if I have a man page file examplecommand.1, how do I install it so that I can just type man examplecommand to view it?

Answer 1

1. First, find out which section your man page belongs to. If its a command, it probably belongs to section 1. You can read the manpage for the man command to see a description of the different sections and their corresponding numbers.

2. Copy your man page to /usr/local/share/man/man1/ (change 1 to your section number if need be). You can also install it to /usr/share/man/man1/, but it's best practice to use the /usr/local/ directory for files that are installed without using the APT package manager. You can also optionally symlink over the file instead of copying it if you want:

   # First, ensure your local man page directory exists for your section of
   # interest (section 1 in this case, so the `man1` dir)
   sudo mkdir -p /usr/local/share/man/man1
   Option 1: copy over the man page to section 1
   sudo cp examplecommand.1 /usr/local/share/man/man1/
   Option 2: symlink over the man page to section 1.
   NB: This cmd assumes you are already cd'ed into the dir in
   which "examplecommand.1" is found, prior to running this cmd.
   sudo ln -si "$PWD/examplecommand.1" /usr/local/share/man/man1/
   

3. Run the mandb command. This will update man's internal database:

   sudo mandb
   

4. That's it! You should be able to view the man page by running:

   man 1 examplecommand
   

---

References:

• The manpage for the man command
• The manpage for the mandb command
• The source code in /usr/bin/dh_installman if you can read Perl, installed with the debhelper package.

Answer 2

If you only need to install the man page locally :

If MANPATH is unset, or includes an empty component (i.e. starts with :, ends with :, or contains ::), then <path>/share/man will automatically be searched for man pages whenever <path>/bin is part of PATH, for all values of <path>.

This provides a very simple way to add man pages for locally installed software. There are some details in man manpath and /etc/manpath.config, but I don't see any mention of the generic mapping from <path>/bin to <path>/share/man.

Answer 3

For an application binary that was copied to ~/.local/bin, copying its .1 man file to ~/.local/share/man/man1 worked for me on Ubuntu 18.04. I had to create the latter directory. I can now access the man page using man <app_name>.

Answer 4

The answer by @ntc2 above is the one people should be looking at. I wanted to add some extra commentary which didn't fit in the comments section:

The approach by @ntc2 provides a path for people only needing to set their PATH (which they already expect) for local binaries.

However, I don't think the generic mapping <path>/bin -> <path>/share/man exists for all paths in $PATH. It seems like this specific mapping is avoided when the $PATH in question is $HOME/bin. When performing strace(1) on man with MANPATH=:/nonexistingdir, I see the following lookups:

For any element in $PATH that's not $HOME/bin

• <path>/bin -> <path>/man
• <path>/bin -> <path>/bin/man
• <path>/bin -> <path>/share/man
• <path>/bin -> <path>/bin/share/man

For $HOME/bin

• $HOME/bin -> $HOME/man

I have no idea why it skips the others. This is on a Debian Buster system. It may be different on other systems.

For me, this means that the safest path to install man-pages is <path>/man, as it's guaranteed to be found if it's in the $PATH.