> ## Content Index
> Fetch the complete content index at: https://linuxhandbook.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Guide to man pages in Linux
- URL: https://linuxhandbook.com/man-pages/
- Published: 2022-07-05T11:01:58.000Z
- Updated: 2025-08-29T05:28:05.000Z
- Description: Though extremely useful, man pages in Linux can be daunting and intimidating at first. This article aims to make it a bit easier to peruse manuals and quickly get the help one needs.
- Author: LHB Community
- Tags: Guides

In the \*nix world, the manual pages, aka man pages, are considered the absolute reference for advanced users. There is also the occasional pedantry of RTFM rudely insisting its importance. The `man` command is even part of the POSIX specification – the basis for most modern implementations of \*nix systems. So is this notion justifiable after all? 

## Advantages of manual pages

- Do not require an internet connection
- Written by the developers/maintainers enabling extensive information and accuracy
- Are self-contained without needing external resources
- Always apply to the installed version of the app and the current distribution

However, even if they may be useful, man pages are daunting at first. This article aims to make it a bit easier to peruse manuals and quickly get the help you need.

## What are manual pages?

Born in the days of Unix, man – short for **manual** – pages were the primary source of user documentation. They were written by the developers of the software and shipped with it.

Today, in Linux distributions, when one installs a package through the package manager – *apt*, *dnf*, *pacman*, or others, the manuals are installed to the `/usr/share/man` directory.

Picking one of those files and using `cat` to view it… has unintended effects

```console
$ cat /usr/share/man/man1/man.1.gz
�[ks�F���_�Ś�IS$m�Ig&��2��b=V��I�6%�
@�F����߾�>��$e�nmR�C��}��}{n�`�3M2Ŀ�
���X�Ϋ;k�����Tm�0˪άi�i*3�f]�u]eֹ��{��
YZ�uzm�q�JK��7N��C�_�4�����|�U����
... # truncated output

```

It must be because the file is compressed. Let's try `zcat`

```console
$ zcat /usr/share/man/man1/man.1.gz
'\" t
.\" ** The above line should force tbl to be a preprocessor **
.\" Man page for man
.\"
.\" Copyright (C) 1994, 1995, Graeme W. Wilford. (Wilf.)
.\" Copyright (C) 2001-2019 Colin Watson.
.\"
.\" You may distribute under the terms of the GNU General Public
... # truncated output

```

Okay, that gives text. But it's still filled with weird syntaxes; also so long that it fills up the entire terminal.

Let's move from adventuring and view the man page as intended—with the `man` command.

```console
$ man man

```

![man page in Linux](https://linuxhandbook.com/content/images/2022/07/man-page-linux.png)

When a man page is accessed using the `man` command, it still fills the terminal window. But now it's easier to read. Additionally, there is a lot of formatting: headings, bold text, italic text or underlined text.

## How are man pages are rendered?

Man pages are markup files written using a descendant of the roff syntax such as [groff from the GNU Project](https://www.gnu.org/software/groff/?ref=linuxhandbook.com). The syntax is a typesetting system that establishes the structure and formatting of the manual pages. This is similar to semantic HTML for webpages.

`man` finds the raw roff file in the filesystem and processes it to generate output suited for the current terminal. The processing involves setting the page width, text encoding, font weights and styles according to terminal support. The output is then displayed using a pager.

The `man` command in Linux is part of the [man-db](https://gitlab.com/cjwatson/man-db?ref=linuxhandbook.com)[ suite of packages](https://gitlab.com/cjwatson/man-db?ref=linuxhandbook.com). There are packages in the collection to handle the various processes and also maintain an index of the installed manuals.

In most BSD systems, the [mandoc project](https://mandoc.bsd.lv/?ref=linuxhandbook.com) project is used instead. And it differs from `man-db` in various aspects. The rest of the article will focus only on `man-db` and its features and options.

## The `man` program

As established earlier, to access a manual page, we use the `man` command. The simplest invocation of the command is `man` followed by the name of the page you want to access. So to access the manual for *ssh*

```console
$ man ssh

```

The elements of the `man-db` suite maintain a shared database of all manual pages that are installed on the system. This database, most likely located at `/var/cache/man/index.db`, acts as a cached index of manual pages. It also provides the information needed by other the other tools in `man-db`. If there is no page in the index with the name *ssh*, the man command searches through a list of directories defined in `/etc/manpath.config` or by the environment variable `$MANPATH`.

### Navigation

Navigation in a man page is handled entirely by the pager that is being used. By default, `man` uses the `pager` command. And in most modern Linux systems `pager` is a [symbolic link](https://linuxhandbook.com/symbolic-link-linux/) to [less](https://linuxhandbook.com/less-command/).

To **close** the manual at any time, simply **press q** on your keyboard. This quits the pager and returns to the shell.

### Scrolling

In most pagers, including `less` it is very easy to scroll through the page using the scroll wheel, scroll gestures and also arrow keys. Home and End are also supported.

Users familiar with Vim can also use the standard keybindings for motions to navigate through the pager. Holding down the j key scrolls down and k scrolls up one line at a time. g and G can be used for the beginning and end of the page respectively.

It is also possible to scroll more at a time using the keyboard, but it often makes reading difficult. But if you wish, you can press the h key to bring up `less`'s help screen for all the keybindings.

![prompt at the bottom of man page instructing the user to press the H key for help and the Q key to quit](https://linuxhandbook.com/content/images/2022/07/h_for_help.jpg)

Being comfortable with scrolling is the first step to using documentation to find information. But even so it would not be easy going through it line by line. That is where the pager's search functionality comes into play.

[Coding for Kids | Game-Based Programming | CodeMonkeyCodeMonkey is a fun and educational game environment where students learn to code in real programming languages, no previous experience needed.![](https://d3sujgifhk94se.cloudfront.net/wp-content/uploads/2019/07/21093608/favicon_banana.gif)CodeMonkey![](https://s3-us-west-2.amazonaws.com/cm-wordpress-media/wp-content/uploads/2018/06/12113810/CodeMonkey-Square-Logo.png)](https://codemonkey.sjv.io/ZdW9d1?ref=linuxhandbook.com)

### Searching

The quickest way to find a particular feature or option in a man page is to search for the word. To initiate a search in the manual press the (forward slash)/ key, type the pattern (regular expressions are supported!) and press Enter

This is useful when you are looking for an approximate "topic." For example, you could open the manual page for `rsync` and search for the word **partial** to quickly jump to the first occurrence of the word. You can then press the n key to move to the next instance or N (shift + n) to go back to the previous one. Using ? you can also search backward.

By default, the case (upper or lower) of the pattern is ignored. But if there is an uppercase letter, the pattern is treated with case sensitivity. This behavior makes it impossible to search for a fully lowercase pattern. And so it is sometimes useful to enable case-sensitive searches. This can be done by pressing the hyphen-i sequence - i to toggle the feature.

Cycling through the instances of the search pattern and scrolling up and down around them is a neat way to get information on a particular topic.

Another good use of the search function is with flags. Performing a search for the pattern that begins the line with spaces and a pattern is useful to jump to the flag.

/`^\s+--compress`

This would also be useful when auditing commands from the internet before running them. Jumping to the flag and verifying what it does. Search can also be used to quickly scroll down to a particular section of the man page.

## Sections of a man page

The manuals are typically divided into multiple sections indicated by the headings displayed in **BOLD UPPERCASE** text. There is a list of sections that are found in most pages. But the common and important ones are name, synopsis, environment and files.

![man page elements in Linux](https://linuxhandbook.com/content/images/2022/07/man-page-elements-linux.png)

### NAME

This section has the name of the application (or manual topic) and a short description. A summary of sorts.

### SYNOPSIS

The synopsis section is a quick start guide. For applications, it is a description of the command line syntax.

It is useful to know the conventions used in the synopsis section that illustrates how the command may be used.

```
command [--optional-flag] [-a -b] [ -c argument ] [-A|-B] filename ...

```

- The first word is the name of the command
- Arguments that are surrounded by `[ ]` are optional
- Flags or options with `|` between them cannot be used together
- Arguments followed by `...` can repeated
- Arguments without `[ ]` are required

With the sample above, `command /etc/passwd` and `command /etc/passwd /etc/group` are the simplest valid invocations having all the required elements.

All the flags listed are optional, but `-A` cannot be used with `-B`. Only one of the two may be used.

Also note that `-c argument` means that **argument** is required if the `-c` flag is used. And only one argument may be passed to `-c`.

### ENVIRONMENT

![ENVIRONMENT section of a man page](https://linuxhandbook.com/content/images/2022/07/ENVIRONMENT-section-man-page-Linux.png)

Environment variables are useful for controlling the behaviour of an application. The environment section of a man page lists the variables that affect a given command and also their effect. The variables that are set by the software for use by other apps are also listed.

You can read more about using environment variables in [our guide on the export command](https://linuxhandbook.com/export-command/)

### FILES

![FILES section of a man page](https://linuxhandbook.com/content/images/2022/07/FILES-element-man-page.png)

The files section of a man page lists and describes paths in the filesystem that are relevant to the software. The paths are typically those of configuration files. The manual page for `bash` lists the initialization files that are parsed by the shell.

💡

Search for the pattern `^ENV` or `^SYN` to quickly scroll to sections without typing the full word!

## man sections

***The sections within a manual are not to be confused with the different sections of man pages.***

Essentially all the manuals available on a system are categorized under sections numbered 1 through 8\. And are installed to their respective folders, `man1` \- `man8`. As you can see in the screenshot below, the ls command is in section 1.

![sections of man command](https://linuxhandbook.com/content/images/2022/07/man-sections-linux.png)

Sometimes a few additional sections also exist. The best description of each section is in the man page for `man` itself.

| Section | Name                                  | Description                                                     |
| ------- | ------------------------------------- | --------------------------------------------------------------- |
| 1       | Executable programs or shell commands | general commands. e.g. cat, man, ssh, cp                        |
| 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          | e.g. /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                                           |

In most cases, it would not be necessary to specify the section. `man` automatically goes through all the sections in a predefined order. But it is possible to specify the section.

```console
man 5 ssh_config
man rsync.1
man "passwd(5)"

```

All the above are valid syntaxes of the command. And the last one – `passwd(5)` refers to the man page for `/etc/passwd`. On the other hand, `passwd(1)` would to the application to change a user's password. In cases like these, it is useful to specify the section.

Often manuals direct the user to refer other related manuals. These references are written in the `name(section number)` format and can be easily copied and pasted into a terminal. But need to be wraped in quotes to prevent the shell from interpreting them.

## Using man command with additional options

While the simplest invocation of `man` is `man name`, it is also possible to use flags to get different results.

#### The `-f` flag for short descriptions

`man -f name` is an alias to `whatis name`, another command available as part of the `man-db` suite. The whatis command prints the short description from the manual page's **NAME** section. The descriptions are extracted and cached in the database that is shared by all `man-db` utilities.

```
$ man -f whatis
whatis (1)	- display one-line manual page descriptions

$ whatis whatis
whatis (1)	- display one-line manual page descriptions

```

#### The `-k` flag to search topics

Similarly, `man -k name` is an alias to `apropos name`. The command searches for **name** in the `man-db` database of descriptions and prints those that have a match. As it searches name and description of each manual, this flag would be useful to find all manuals on a topic.

```console
$ man -k apropos
apropos (1)	- search the manual page names and descriptions

$ apropos apropos
apropos (1)	- search the manual page names and descriptions

$ man -k password
chage (1)	- change user password expiry information
chgpasswd (8)	- update group passwords in batch mode
chpasswd (8)	- update passwords in batch mode
... #truncated

```

#### View with `--html`

```console
$ man --html

```

The `--html` flag can be used to generate html output! `man` will even open the browser and display the html version of the manual. Note that this depends on the `$BROWSER` environment variable being valid.

There are other CLI options that are listed in `man(1)` and they can be viewed using the command `man man`. 😉

### Alternative documentation

Despite its utility, `man` is not always the answer. Sometimes grepping the help prompt for a term is all one needs.

```console
$ command --help | grep -i 'term'

```

Most programs have a help prompt accessible using the `--help` flag. However, `man` remains the best way to get in-depth information.

But `man` is not the only answer. There have been various competing standards for software documentation. [GNU's texinfo](https://www.gnu.org/software/texinfo/?ref=linuxhandbook.com), web-only documentation that is published on websites or on GitHub are not uncommon.

![How Standards Proliferate (See: A/C chargers, character encodings, instant messaging, etc.) Situation: There are 14 competing standards. Cueball: 14?! Ridiculous! We need to develop one universal standard that covers everyone's use cases. Ponytail: Yeah! Soon: Situation: There are 15 competing standards.](https://imgs.xkcd.com/comics/standards.png)

Image source: [xkcd](https://imgs.xkcd.com/comics/standards.png?ref=linuxhandbook.com)

Despite it all `man` has stood the tests of time and persists today. Its flexibility and availability play a large role. The depth of information has an equally big role. Hopefully, this article has guided you to embrace it. And next time, maybe you too will reach for the man pages before a search engine.

*This article has been contributed by* [*Kevin Samuel*](https://kevinnlsamuel.com/?ref=linuxhandbook.com)*.*