64

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?

dessert
  • 39,392
  • 12
  • 115
  • 163
Flimm
  • 40,306
  • 22
  • 94
  • 154

4 Answers4

71

  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:

Gabriel Staples
  • 8,025
  • 7
  • 66
  • 105
Flimm
  • 40,306
  • 22
  • 94
  • 154
  • 1
    Is there an option or what is the recommended practice when you would like to avoid using `sudo`? – Jorge Bucaran Dec 07 '15 at 07: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 03 '17 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 '19 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.

ntc2
  • 636
  • 7
  • 17
  • I appended `MANPATH=:$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 02 '19 at 07: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 `/bin` -> `/share/man` exists. When performing strace(1) on `man` with `MANPATH=:/nonexistingdir`, I see the following: - `/bin` -> `/man` This is on a Debain Buster system. – Aktau Jan 16 '19 at 09: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>.

Asclepius
  • 940
  • 1
  • 7
  • 14
  • 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). – Yaroslav Nikitenko Jul 12 '22 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.

Aktau
  • 121
  • 3