How To – Linux / UNIX Create a Manpage

How do I create a man page for my shell or python scripts under Linux / UNIX-like operating systems?

Almost all UNIX like oses comes preinstalled with man pages.

Troff and Groff Macro

troff is a document processing system developed by AT&T for the Unix operating system. The troff typesetting system includes sets of commands called macros that are run before starting to process the document. These macros include setting up page headers and footers, defining new commands, and generally influencing how the output will be formatted. Under Linux all new manual pages should be marked up using the groff an.tmac package. The groff (GNU troff) software is a typesetting package which reads plain text mixed with formatting commands and produces formatted output.

A Quick Note About Man Page Layout

All man pages follow a common layout and it is recommend that you use the same for your man pages too:

    The name of the command or function, followed by a one-line description of what it does.
    In the case of a command, you get a formal description of how to run it and what command line options it takes.
    A textual description of the functioning of the command or function.
    Some examples of common usage.
    A list of related commands or functions.
    List known bugs.
   Specify your contact information.
    Specify your copyright information.

You can add a few more other sections such as EXIT STATUS, ENVIRONMENT, FILES, and HISTORY etc. The table below shows the section numbers of the manual followed by the types of pages they contain.

Man Page Sections

The manual is generally split into eight numbered sections, organized as follows under Linux or UNIX like oses:

Section Description
1 Executable shell commands
2 System calls (functions provided by the kernel)
3 Library calls (functions within program libraries)
4 Special files (usually found in /dev)
5 File formats and conventions eg /etc/passwd
6 Games
7 Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8 System administration commands (usually only for root)
9 Kernel routines [Non standard]

To see options and section information you can use with command man, enter the following command:

man man

Man Page Location

The system stores its man pages at /usr/share/man/ directory as described in about section. For example, the directory /usr/share/man/man1 stores man pages for user shell commands. You can view it by typing the following command:

cd  /usr/share/man/man1
ls -l
zcat ls.1.gz

Custom Man Page Location

It is recommended that you store your own man pages in /usr/local/man directory. You can set man search path in /etc/man.config file:

MANPATH /usr/man
MANPATH /usr/share/man
MANPATH /usr/local/man
MANPATH /usr/local/share/man
MANPATH /usr/X11R6/man

See manpath man page for more details about how to determine search path for manual pages:
man manpath

How Do I Create My Own Man Page?

The groff (GNU Troff) software is a typesetting package which reads plain text mixed with formatting commands and produces formatted output such as man page. It comes with various macro packages such as man and mandoc to create man pages. Create a file as follows
$ vi nuseradd

.\" Manpage for nuseradd.
.\" Contact to correct errors or typos.
.TH man 8 "06 May 2010" "1.0" "nuseradd man page"
nuseradd \- create a new LDAP user 
nuseradd [USERNAME]
nuseradd is high level shell program for adding users to LDAP server.  On Debian, administrators should usually use nuseradd.debian(8) instead.
The nuseradd does not take any options. However, you can supply username.
useradd(8), passwd(5), nuseradd.debian(8) 
No known bugs.
Vivek Gite (

Save and close the file. To view your man page, enter:

man ./nuseradd

Sample outputs:

Fig.01 Man page in action

The .TH macro introduces a manual page (e.g., set man page title and section). Section headers, paragraph breaks, lists and displays etc displayed using .SH macro. See the following man page which describes all macros:
man 7 mdoc

How Do I Install My Man Page?

Simply type the following command:

cp nuseradd /usr/local/man/man8/nuseradd.1
gzip /usr/local/man/man8/nuseradd.1
man nuseradd

You can also use install command as follows (recommend for shell scripts):

install -g 0 -o 0 -m 0644 nuseradd.1 /usr/local/man/man8/
gzip /usr/local/man/man8/nuseradd.1


You learned how to create a man page under Linux and Unix like systems. Please the following resources for more info:

  • GNU Troff (Groff) – a GNU project.
  • See man pages mdoc, groff, and install commands.
This entry is 5 of 6 in the Installing and Using Man Pages Tutorial series. Keep reading the rest of the series:
  1. How to add/install man pages in Alpine Linux
  2. How to install man pages on a CentOS Linux 6/7
  3. Unix / Linux: Display Color Man Pages
  4. Linux / UNIX: Getting help with man pages and how to use them
  5. HowTo: Linux / UNIX Create a Manpage
  6. Ubuntu Linux install man pages

🐧 Get the latest tutorials on Linux, Open Source & DevOps via RSS feed or Weekly email newsletter.

🐧 19 comments so far... add one

CategoryList of Unix and Linux commands
Disk space analyzersdf duf ncdu pydf
File Managementcat cp mkdir tree
FirewallAlpine Awall CentOS 8 OpenSUSE RHEL 8 Ubuntu 16.04 Ubuntu 18.04 Ubuntu 20.04
Modern utilitiesbat exa
Network UtilitiesNetHogs dig host ip nmap
OpenVPNCentOS 7 CentOS 8 Debian 10 Debian 8/9 Ubuntu 18.04 Ubuntu 20.04
Package Managerapk apt
Processes Managementbg chroot cron disown fg glances gtop jobs killall kill pidof pstree pwdx time vtop
Searchingag grep whereis which
User Informationgroups id lastcomm last lid/libuser-lid logname members users whoami who w
WireGuard VPNAlpine CentOS 8 Debian 10 Firewall Ubuntu 20.04
19 comments… add one
  • VIKAS Jul 18, 2012 @ 11:45

    Hi Vivek,

    Excellent article. I just learnt to write man pages for my shell scripts.

    I just found one mistake, I believe below lines

    cp nuseradd /usr/local/man/man8/nuseradd.1
    gzip /usr/local/man/man8/nuseradd.1

    should be

    cp nuseradd /usr/local/man/man8/nuseradd.8
    gzip /usr/local/man/man8/nuseradd.8


    • robot Oct 30, 2016 @ 8:18

      Nice, it fixed my issue.

  • randy Mar 1, 2013 @ 0:03

    Very nice. I am just getting feet wet with my own scripts. I had started to put man style text right in script files and cat them out on demand for –help. This a so much better and fun!
    Hint: peek into the files at /usr/share/man to get to know more about write the markup the man pages use.

  • Greg Feb 21, 2014 @ 15:40

    Thank you for writing this tutorial about creating man pages. I encountered an issue when deploying the man page which I created. When I ran man my_script it reported “No manual page for my_script.” I found the step missing in your otherwise excellent introductory-level tutorial; the ‘mandb’ command must be executed before man my_script displays as anticipated. Hopefully, you read these comments and update your tutorial.

  • David Gamba Apr 7, 2014 @ 14:00

    Thanks for the article, was looking for the right place to put the man file.
    I Usually write my man pages in Asciidoc format ( and then convert them to different outputs depending on need, in general html and troff. Another cool thing about it (besides the fact that you write once in an easy to write/read format and publish in many) is that github understands Asciidoc documents (.adoc or .asciidoc) so you can use that same write up for your README and if not, then you can read the documentation for your script without having to even generate the html output.

  • Adam Hall Aug 3, 2014 @ 10:28

    Thanks for the walkthrough! I have been steadily creating more applications and started to get into a need for a man page. This helped me out big time! Would have been nice if you could have had some entries into some of the categories to give a little more detailed example… but I figured it out.


  • Sashidhar Nov 20, 2014 @ 19:05

    Works exactly as described. But 2 issues:
    (a) One one machine, it did generated no error, no logs, but did not generate a man page. Would appreciate if someone knows the issue.
    uname: Linux 2.6.18-348. #1 SMP Thu Sep 26 13:34:56 PDT 2013 x86_64 x86_64 x86_64 GNU/Linux
    man version: 1.6d
    (b) Everytime, I have to say “man /path_name/function_name”. It should be possible without the path. I have already set the MAN_PATH to include the path. If anyone else can point to a treatise on man also, it will be nice.
    (c) mandb is not installed on my office machines, although my home machine has it. And even on my home machine, after running `mandb` it says “1 subdirectory contained newer man pages”, but even after that, it says “No manual entry for” my function. So any info on mandb also is helpful. I will update my own comment if I find solutions.

  • jzeng May 30, 2015 @ 3:55

    I wanna to know that why the editor need to use vi, when I firstly use vim, it cannot work at all, I want to know about the reason.

  • Vijay Cheruvu Aug 12, 2015 @ 8:04

    Vivek: Thanks a lot for your article. Great.

  • Sreekar Guddeti Sep 8, 2015 @ 11:51

    Thanks for the helpful tip on writing custom man pages for custom scripts

  • aytizzoo Nov 21, 2015 @ 3:52

    how I create man?

  • aneela May 4, 2016 @ 23:43

    i don’t have any permission to /usr/local/man/man1/

    Want should i need to do.

    Thanks in advance.

    • mustafa May 10, 2017 @ 10:47

      write sudo to and Entre root password

  • Vishal Kothari Jan 10, 2017 @ 9:44

    Just created my first man page with this simple sequence of commands. :) Thank you.

  • mustafa May 10, 2017 @ 10:49

    i have an error ,, it cannot cp my file and it wrote no file or directory buy when iam write man ./filename it show the content what should i do to fix this error

  • joker Oct 29, 2020 @ 12:25

    sir i try a lot to install man page but it shows install: target `/usr/local/man/man8/’ is not a directory: No such file or directory
    pls reply

    • 🐧 Vivek Gite Oct 29, 2020 @ 14:11

      Create that dir /usr/local/man/man8/:
      mkdir -p -v /usr/local/man/man8/

  • Atv Oct 30, 2020 @ 22:43

    I was struggling with the formatting of the manpage to be accepted by the dh_installman for many hours until finally I found your example that finally did the trick.
    Thank you a lot for sharing!

Leave a Reply

Your email address will not be published.

Use HTML <pre>...</pre> for code samples. Still have questions? Post it on our forum