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?
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.
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/
Run the mandb
command. This will update man
's internal database:
sudo mandb
That's it! You should be able to view the man page by running:
man 1 examplecommand
man
command mandb
command /usr/bin/dh_installman
if you can read Perl, installed with the debhelper
package.sudo
?
/usr/local/man
as well as suggested in PATH to MANPATH mapping in /etc/manpath.config
.
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
.
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
<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.
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>
.
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
.