49

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?

60
  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 Manpage icon 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 practise to use the local directory for files that are installed without using the APT package manager:

    sudo cp 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:

3
  • 1
    Is there an option or what is the recommended practice when you would like to avoid using sudo? – Jorge Bucaran Dec 7 '15 at 7:02
  • @JorgeBucaran See the answer below on how to set MANPATH, which allows you to put manual pages in spaces you can write to, e.g. $HOME/lib/share/man or somewhere like that – nealmcb Sep 3 '17 at 20:58
  • I think you could store the man pages under /usr/local/man as well as suggested in PATH to MANPATH mapping in /etc/manpath.config . – jarno Aug 12 '19 at 13:51
11

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.

2
  • I appended MANPATH=<local path to the man pages>:$MANPATH to your ${HOME}/.bashrc (non-login sessions) or ${HOME}/.profile (login sessions). In my case, I set up a local directory for man pages in ${HOME}/share/man/, which mimicks the classical Linux filesystem. I created ${HOME}/share/man/man.1, which then contains a symbolic link to the location to the file examplecommand.1 wherever the program installer has put it (the configure 'prefix'). Launching man examplecommand finds the man pages in point. In this way the installation is local, though, not system-wide. – XavierStuvw Jan 2 '19 at 7:55
  • This was a very interesting comment, and it 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. When performing strace(1) on man with MANPATH=:/nonexistingdir, I see the following: - <path>/bin -> <path>/man This is on a Debain Buster system. – Aktau Jan 16 '19 at 9:16
2

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.

0

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>.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.