65

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?

4 Answers 4

75
  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 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:

3
  • 1
    Is there an option or what is the recommended practice when you would like to avoid using sudo?
    – j--
    Dec 7, 2015 at 7:02
  • 1
    @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, 2017 at 20:58
  • 1
    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, 2019 at 13:51
20

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. Jan 2, 2019 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, 2019 at 9:16
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>.

1
  • Do you have any official reference to this local man path? (small comment: not Ubuntu, but on Arch Linux this path means nothing by default, it is not automatically searched). Jul 12, 2022 at 19:21
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.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .