I have added extra directories to $PATH
by exporting PATH=/my/dirs:$PATH
But I am not sure if I should do the same to MANPATH
. Because default MANPATH
is empty yet man
command works. I found a command called manpath
and its manual says If $MANPATH is set, manpath will simply display its contents and issue a warning.
. Does this mean setting MANPATH is not the right way to add directories for man
command to search for manual pages?
3 Answers
If you simply set MANPATH, it overrides the default and you lose access to the standard man pages. For example, man ls
works before setting MANPATH, but does not work afterwards.
To append a search directory without overriding the default, prefix a colon to MANPATH like this:
export MANPATH=":/path/to/custom/man"
Adding the colon gives you access to both the standard system man pages and the custom pages referenced in the MANPATH variable.
This answer brought to you by manpath(1):
If $MANPATH is set, manpath displays its value rather than determining it on the fly. If $MANPATH is prefixed by a colon, then the value of the variable is appended to the list determined from the content of the configuration files. If the colon comes at the end of the value in the variable, then the determined list is appended to the content of the variable. If the value of the variable contains a double colon (::), then the determined list is inserted in the middle of the value, between the two colons.
While the title specifically mentions the MANPATH
variable, I believe what the original author of the question was partly alluding to was whether there is a way to "add" a manpage to the system without touching the MANPATH variable in the first place.
Therefore, in addition to the accepted answer, I would point out that, in a standard configuration, the manpage
command also seems to look at directories in your PATH
.
I have not come across the relevant documentation for this, but from personal experimentation, I think the way this works is as follows:
Assume you have a directory in your PATH called /dir1/dir2/dir3/dir4
.
Then, dir4
as well as its parent (i.e. dir3
) will be searched by manpath
, and if one of those directories contains a sub-directory called man
or share/man
, then the 'man' directory in question will be added to the output of the manpath
command.
In practice this means that, e.g., if /home/user/.local/bin
is in your path, and you also have a directory called /home/user/.local/share/man
, any manpages contained there will be picked up. Similarly, if something like /opt/nano/bin
is in your path, then /opt/nano/share/man
will be picked up.
Note that by "picked up", I mean that the manpath
command will include that directory in its output! The content of those directories still needs to be compatible with man
for man
to pick up valid manpages from within them. In other words, your home/user/.local/share/man
directory should contain a man1
directory containing lots of .1
files, a man5
directory containing lots of .5
files, etc, in groff format.
UPDATE: As per the comments below, the manpath
man pages now fully document this behaviour as of man-db 2.10.0.
-
-
@ReubenThomas thanks Reuben, but that page still doesn't mention the above. The closest thing
man 5 manpath
hints at is that you can have 'fixed' path-to-manpath conversions. I haven't seen any documentation regarding 'relative' conversions as shown above. Not sure why; it's an incredibly useful mechanism! Jan 20, 2022 at 11:48 -
Indeed, and I have filed a bug requesting this documentation: savannah.nongnu.org/bugs/?61862 Jan 20, 2022 at 18:55
-
-
1In response to that bug report, there's now a dedicated section for this (manpages.ubuntu.com/manpages/jammy/en/man5/…) and the other manual pages in man-db refer to that. Feb 9, 2022 at 0:00
You should add your custom directories at the end of your PATH
:
PATH=$PATH:/my/dirs
This is so your custom directories do not override system binaries and libraries, which could cause a security issue.
You set MANPATH
the same way (MANPATH
is empty by default):
MANPATH=$MANPATH:/my/dirs
You should not need to set a MANPATH
with well behaved packages, so if it is not broken don't fix it. If it is broken, perhaps you are better filing a bug report ;)
Add this to ~/.bashrc
:
export PATH=$PATH:/my/dirs
export MANPATH=$MANPATH:/my/dirs
-
Typo in the second statement?
MANPATH=$MANTPATH:/my/dirs
Maybe should be:MANPATH=$MANPATH:/my/dirs
Nov 11, 2013 at 9:25 -
What do you mean by "well behaved packages"? I have a whole set of tools that are not installed in the usual places (HPC clusters often put things in /opt). How should they register their man pages without using $MANPATH?– i_grokMar 15, 2014 at 15:30
-
"well behaved packages" are written to use standard paths and environmental variables. Poorly behaved packages use non standard, at least to Ubuntu, paths such as /opt or do not use environmental variables and thus lead to your observation " I have a whole set of tools that are not installed in the usual places (HPC clusters often put things in /opt)"– PantherMar 15, 2014 at 16:55