whatis Command in Linux: Complete Guide to One-Line Command Descriptions and Parameters

There’s a specific moment every Linux user hits: you half-remember a command name, you know roughly what it does, but you don’t want to wade through a full man page just to confirm you’ve got the right tool. That’s exactly the itch whatis scratches. It’s a small, unglamorous command, but I reach for it constantly, especially when I’m scanning through a bunch of unfamiliar binaries on a new system and just want a quick sanity check on what each one does before I commit to reading the full documentation.

What whatis Does

whatis searches the system’s manual page database and prints the one-line NAME description for a given command — nothing more, nothing less. It doesn’t show you syntax, options, or examples; it shows you exactly the summary line that sits at the top of every man page under the NAME heading.

I tested it directly on my system after making sure the manual page database was populated:

$ whatis ls
ls (1)               - list directory contents

$ whatis grep
grep (1)             - print lines that match patterns

$ whatis sort
sort (1)             - sort lines of text files

That (1) is the man page section number — section 1 covers user commands, which is where most everyday utilities live. I’ll get into sections in a bit because they matter more than people expect.

Why whatis Sometimes Says “Nothing Appropriate”

Before whatis can find anything, the manual page index (built by mandb) has to exist and be up to date. On a freshly stripped-down system — cloud images and minimal container bases do this constantly — the man page database is often empty or missing entirely. I ran into this directly:

$ whatis ls
ls: nothing appropriate.

The fix is to (re)build the index with mandb, which scans everything under your MANPATH and generates the lookup database that whatis and apropos both depend on:

$ sudo mandb

After that finished, the same query worked correctly:

$ whatis ls
ls (1)               - list directory contents

If mandb itself isn’t installed (common on Debian/Ubuntu minimal images), you need the man-db package:

$ sudo apt install man-db

Basic Syntax

whatis [options] keyword...

You can query more than one keyword in a single call:

$ whatis ls grep sort
ls (1)               - list directory contents
grep (1)             - print lines that match patterns
sort (1)             - sort lines of text files

Key Options

Wildcard Search with -w

$ whatis -w 'grep*'
grep (1)             - print lines that match patterns

I use -w when I only half-remember the exact command name — it’s forgiving in a way a plain lookup isn’t.

Regex Search with -r

$ whatis -r '^git-'

This is genuinely useful on systems with a lot of installed tooling that follows a naming convention (like git’s plumbing commands, all prefixed git-), letting you list an entire family of related tools at once.

Restricting to a Man Section with -s

Some names exist in multiple man sections with completely different meanings. A classic case is passwd — there’s the command (section 1) and the file format (section 5):

$ man -f passwd
passwd (1)           - change user password
passwd (5)           - the password file

(man -f is functionally identical to whatis — more on that below.) If I only care about the command, not the file format:

$ whatis -s 1 passwd
passwd (1)           - change user password

whatis vs. man -f

This trips people up: man -f and whatis are the same operation. man -f is literally implemented as a call into the same lookup that whatis performs. I verified this produces identical output:

$ man -f ls
ls (1)               - list directory contents

$ whatis ls
ls (1)               - list directory contents

Use whichever you find more memorable — I default to whatis because it’s fewer keystrokes and reads more naturally.

How It Works Internally

Understanding the plumbing makes the tool far less mysterious:

1. Man pages are stored as compressed troff/groff source files, typically under /usr/share/man/man1/, /usr/share/man/man5/, /usr/share/man/man8/, and so on, organized by section number and often gzip-compressed (.gz).
2. mandb walks every directory in MANPATH, opens each man page, extracts the NAME section (the one-liner at the top: name - short description), and writes it into a binary database, usually at /var/cache/man/index.db (Berkeley DB format on most modern systems).
3. whatis doesn’t parse man pages at query time at all. It just does a fast key lookup against that prebuilt index. This is exactly why it’s instant even on systems with thousands of installed man pages, and also exactly why it goes stale — if you install new software and never run mandb, whatis won’t know about it until the index is rebuilt.
4. Most distros configure a periodic cron/systemd timer job (man-db.timer on systemd systems) that reruns mandb automatically, usually daily, so the index self-heals over time even if you never touch it manually.

Practical Use Cases

Quickly auditing an unfamiliar binary before running it:

$ whatis strace
strace (1)           - trace system calls and signals

Sanity-checking scripts you’re reviewing. If a shell script calls a command I don’t recognize, whatis is faster than opening a browser:

$ whatis dd
dd (1)               - convert and copy a file

Disambiguating identically-named tools across sections, as shown with passwd above — this matters a lot when you’re reading configuration references and a man command says “see crontab(5)” versus “see crontab(1)”. Those are two entirely different documents (the command vs. the file format), and whatis -s lets you confirm which one you’re looking at before opening it.

Scripting a quick documentation coverage check. I’ve used this in onboarding scripts to warn engineers about tools installed on a box that don’t have accompanying documentation:

#!/bin/bash
# Warn about commands in /usr/local/bin with no man page entry
for cmd in /usr/local/bin/*; do
    name=$(basename "$cmd")
    if ! whatis "$name" &>/dev/null; then
        echo "No man page found for: $name"
    fi
done

Troubleshooting

“nothing appropriate” for a command you know exists:

1. Confirm the man page itself is actually installed: man command_name. If man itself fails too, the package that ships the documentation may be missing or was deliberately stripped (common on minimal cloud/container images that exclude /usr/share/man/* at the package-manager level to save space).
2. Rebuild the index: sudo mandb.
3. Check MANPATH isn’t misconfigured: manpath shows the effective search path; compare it against where the man pages actually live.

whatis works for some commands but not others on the same system: This almost always means selective installation — some packages ship man pages, others (especially minimal or stripped builds) don’t. Reinstalling the specific package, or installing a distro’s bundled manpages/manpages-dev package, restores the missing entries.

Output looks truncated or missing a section: Some very minimal packages provide man pages with an empty or malformed NAME section. whatis can only report what the page actually contains — if the page itself is broken, no index rebuild will fix that; it’s a packaging issue upstream.

whatis, apropos, and man -k — Untangling the Trio

These three commands are related enough to cause real confusion, so I want to be precise:

I verified the difference directly:

$ whatis partition
partition: nothing appropriate.

$ apropos partition
proc_partitions (5)  - major and minor numbers of partitions

whatis needed the exact command name and found nothing named “partition.” apropos searched descriptions and found a match. If you’re not sure of the exact name, apropos (covered in its own guide) is the better starting point; once you know the exact name, whatis is faster and more precise.

Best Practices

• Run sudo mandb right after any bulk software installation on a server, especially if you’ve compiled anything from source and installed man pages manually into a nonstandard path — those won’t show up until the index is rebuilt.
• Prefer whatis -s 1:8 scoping when working across sections that share names, to avoid confusing a command with a configuration file format.
• Don’t rely on whatis for anything beyond a one-line sanity check — for actual usage details you still need man command_name.
• On automated provisioning (Ansible, cloud-init, Dockerfiles), explicitly install a distro’s manpages package if your tooling or team relies on whatis/apropos/man — many base images strip documentation by default to reduce image size.

Performance Notes

Because whatis reads from a prebuilt binary index rather than scanning files, it’s effectively instantaneous regardless of how many man pages are installed — I’ve never seen it take a perceptible amount of time even on systems with several thousand pages indexed. The only performance cost lives in mandb, which does the actual file scanning and can take anywhere from a few seconds to over a minute on a system with a large documentation set (particularly manpages-dev and language-specific doc packages, which add thousands of entries).

Locale and Language Considerations

whatis output respects your system’s configured locale when multiple language translations of a man page exist. If a page has been translated and installed for your LANG setting, whatis will show the translated description rather than the English original. This occasionally surprises people running non-English locales who expect consistent English output in scripts. If you’re parsing whatis output programmatically and need consistent results regardless of the operator’s locale, force it explicitly:

$ LC_ALL=C whatis ls
ls (1)               - list directory contents

I do this reflexively in any script that consumes whatis output for automated processing, for the same reason I force LC_ALL=C with sort — reproducibility across machines with different locale configurations matters more than cosmetic localization when the output feeds into other tooling rather than being read directly by a human.

Combining whatis with Other Commands

whatis is small enough that its real value often comes from combining it with other tools rather than using it in isolation.

Listing every command in a directory with its description, useful for quickly auditing what’s installed in a nonstandard bin directory:

$ for cmd in /usr/local/bin/*; do
    whatis "$(basename "$cmd")" 2>/dev/null
done

Filtering whatis output for commands matching a pattern, when you want descriptions but only for a specific naming convention:

$ whatis -w 'git*' | grep -v "nothing appropriate"

Building a quick reference sheet for a specific toolset before onboarding a new team member — pulling every relevant command’s one-liner into a single document:

$ for cmd in ssh scp rsync tar gzip; do whatis "$cmd"; done > quick-reference.txt

I’ve used variations of this last pattern more than once when handing off a server to someone less familiar with the specific toolchain in use — a five-minute script produces a genuinely useful cheat sheet pulled straight from the system’s own documentation, guaranteed to match the actual installed versions rather than a generic guide that might describe different behavior.

whatis in the Context of Shell Completion and Discoverability

Some shells and terminal tools integrate whatis-style lookups into tab-completion or help systems, showing a command’s one-line description alongside completion suggestions. This isn’t whatis itself doing the work in those cases, but it’s built on the exact same underlying man-db index — which is one more reason keeping that index current with periodic mandb runs pays off beyond just the whatis command directly. A well-maintained documentation index quietly improves several other tools’ behavior at once, not just the one you’re deliberately invoking.

A Note on Custom and In-House Tools

If you maintain internal scripts or tools for your own infrastructure, writing a proper man page for them (even a minimal one) and running mandb afterward makes them fully discoverable through whatis and apropos alongside every standard system utility. I’ve started doing this for anything I expect other people on a team to eventually use — it costs relatively little effort (a short groff-formatted file following the standard NAME/SYNOPSIS/DESCRIPTION structure) and it means a colleague unfamiliar with an internal tool can run whatis toolname or man toolname and get a real answer instead of having to track someone down or dig through source code comments.

Compatibility Across Distributions

whatis is part of the man-db package, which is the standard man page implementation across virtually every modern Linux distribution — Ubuntu, Debian, Fedora, RHEL/CentOS/Rocky/Alma, Arch, openSUSE. Behavior and options are consistent across all of them since they share the same upstream man-db project. The one thing that varies is whether man pages are installed by default — Debian/Ubuntu minimal cloud images strip them out entirely by default via dpkg path exclusions, while most desktop-oriented installs and traditional server ISOs keep them.

Summary

whatis gives you the one-line NAME description for a command by doing a fast, exact-match lookup against the prebuilt man-db index — the same index apropos and man -k search more broadly, and the same operation man -f performs under a different name. It’s not a substitute for reading a full man page, but as a “what does this thing even do” gut check, it’s hard to beat for speed. If it comes back empty on a command you know is installed, the fix is almost always sudo mandb to rebuild the index, or installing your distro’s manpages package if documentation was stripped out entirely.

References

• man man-db and man whatis — official man-db project documentation
• man-db project homepage — https://gitlab.com/man-db/man-db
• Debian man-db package page — https://packages.debian.org/man-db