whereis Command in Linux: Complete Guide to Finding Binary, Source, and Manual Files and Parameters

I didn’t really understand what whereis was for until I ran it side-by-side with which on the same command and got noticeably different results. which told me where the binary I’d actually run lives; whereis told me that, plus where its man page was, and — on systems that still have source packages installed — where its source lived too. That extra context turned out to be genuinely useful for a specific kind of investigation: figuring out whether documentation exists for a tool, or confirming that a package installed all the pieces it was supposed to, not just the executable. This guide covers whereis end to end.

What Is the whereis Command?

whereis locates the binary, source, and manual page files associated with a given command name, by searching a fixed, built-in list of standard system directories — not the PATH environment variable the way which does. It’s part of the util-linux package and ships on essentially every Linux distribution.

Basic Syntax

whereis [OPTIONS] NAME...

A Basic Example

$ whereis ls
ls: /usr/bin/ls

By default, whereis searches for all three categories (binary, source, manual) and reports whichever it finds. In a minimal container image without man pages installed, you’ll often see just the binary path, as above — there’s no source or manual entry because those files simply aren’t present on the system.

Full Parameter Reference

Option	Description
-b	Search only for binaries
-m	Search only for manual page entries
-s	Search only for source files
-u	Search for “unusual” entries — commands missing one of the expected categories, useful for auditing incomplete installs
-B <dirs>	Specify custom directories to search for binaries (must be followed by -f to terminate the directory list)
-M <dirs>	Specify custom directories to search for manuals
-S <dirs>	Specify custom directories to search for source
-f	Terminates a -B/-M/-S directory list before the command name(s) begin
-g	Interpret the name as a glob pattern for matching
-l	Print the effective list of directories whereis will search
-h, --help	Display usage information
-V, --version	Display version information

-b: Binaries Only

$ whereis -b bash
bash: /usr/bin/bash

-m: Manual Pages Only

$ whereis -m bash
bash:

An empty result after the colon means no man page was found in the standard manual directories — common in stripped-down containers or minimal installs where the man-db package and documentation files were never installed.

-l: Showing the Search Path

This is worth running once on any new system, because it tells you exactly where whereis is looking, which explains why it might report “nothing found” for a tool you know is installed somewhere non-standard:

$ whereis -l
bin: /usr/bin /bin /usr/sbin /sbin ...
man: /usr/share/man ...

(Exact directories vary by distribution and configuration.)

How whereis Works Internally

This is the most important conceptual distinction between whereis and which, and it’s worth being precise about: whereis does not consult the PATH environment variable at all. Instead, it has a hardcoded (though somewhat distribution-configurable) list of conventional system directories where binaries, source code, and manual pages are expected to live — directories like /usr/bin, /bin, /usr/local/bin for binaries, and /usr/share/man, /usr/local/man for manual pages.

For each name given, whereis strips any leading path and trailing common suffixes (like .c for source files) and then checks each configured directory category for a matching file, reporting every match it finds in each category — not just the first one, unlike which‘s default single-result behavior.

Because it searches fixed system locations rather than your personal, possibly-customized PATH, whereis gives you a picture of what the system considers the canonical install locations for a tool, which can differ from what your shell would actually execute if your PATH has been customized with, say, a ~/bin or a language version manager’s shim directory prepended.

which vs whereis: A Direct Comparison

Aspect	which	whereis
Searches	Directories listed in $PATH	Fixed list of standard system directories
Finds	Executable binaries only	Binaries, source files, and manual pages
Respects custom PATH	Yes	No
Typical use	“What will run when I type this command?”	“Is this command fully installed, including docs/source?”
Speed	Very fast, few directories	Very fast, but checks more categories

A concrete illustration: if you’ve built and installed a custom version of a tool into ~/local/bin and prepended that to your PATH, which tool will correctly report ~/local/bin/tool as what actually runs. whereis tool, meanwhile, will likely report the older, distro-packaged binary in /usr/bin/tool instead (if one exists), because that’s within its standard search locations and ~/local/bin typically isn’t.

Real-World Use Cases

1. Confirming a Package Installed Documentation, Not Just the Binary

$ whereis rsync
rsync: /usr/bin/rsync /usr/share/man/man1/rsync.1.gz

If the man page entry is missing after installing a package, that’s a signal the -doc or equivalent documentation sub-package wasn’t installed alongside the main tool — common on minimal/--no-install-recommends installs.

2. Auditing for Incomplete Installations

$ whereis -u *

The -u flag combined with a glob (shell-expanded here, not whereis‘s own -g) surfaces commands that are missing an expected category, which is a quick way to spot broken or partial installs across a directory of binaries.

3. Finding Source Packages on Development Systems

On systems where source packages are installed alongside binaries (common in some development or research environments), -s narrows results to just the source location:

$ whereis -s vim

4. Quickly Checking If Documentation Exists Before Writing Your Own

Before I write internal documentation for a tool, I check whether man pages already cover it:

$ whereis -m tool_name

If there’s a result, man tool_name is worth reading first.

Shell Scripting and Automation

A small audit script that reports which installed binaries in a custom directory are missing man pages — useful when packaging in-house tools and wanting to catch gaps before release:

#!/bin/bash
# audit_manpages.sh - flag binaries in /usr/local/bin missing man pages
set -euo pipefail

for bin in /usr/local/bin/*; do
    name=$(basename "$bin")
    result=$(whereis -m "$name")
    # result format is "name:" with nothing after the colon if no manual found
    if [[ "$result" == "$name:" ]]; then
        echo "Missing man page: $name"
    fi
done

whereis vs Related Commands

Command	Purpose
whereis	Locates binary, source, and manual files in standard system directories
which	Locates the executable that would run based on $PATH
locate	Fast filename search across the entire filesystem using a prebuilt database
find	Real-time, filter-rich filesystem search, slower but exhaustive and always current
man -w (man --path)	Reports the path to a specific man page without displaying it
apt-file / dnf provides	Finds which package provides a given file, useful before installation

whereis sits in an interesting middle ground: narrower than find or locate (it only looks in standard, conventional locations), but broader than which in what categories of file it reports on.

Troubleshooting Common Issues

Problem: whereis reports nothing for a command I know is installed. The binary is likely installed outside whereis‘s standard search directories (e.g. /opt/tool/bin, a user’s home directory, or a language-specific install path like ~/.cargo/bin or ~/.local/bin). Confirm with which (which respects PATH) or find / -name toolname 2>/dev/null for an exhaustive search.

Problem: Man page section shows empty even though man toolname works fine. Some systems configure MANPATH or use mandb-indexed locations that fall outside whereis‘s hardcoded default list, especially after custom MANPATH configuration. Cross-check with man -w toolname or manpath to see the actual man search path in effect.

Problem: -B/-M/-S custom directory options don’t seem to take effect. Remember these require a terminating -f before the command name arguments begin — omitting it can cause whereis to misinterpret where the directory list ends and the search terms begin.

Performance Optimization

whereis is fast by design — it checks a small, fixed set of well-known directories rather than walking the entire filesystem, so there’s essentially no performance tuning needed. It’s meaningfully faster than find / -name toolname for the common case, precisely because it doesn’t recurse through the whole filesystem tree; it only checks conventional top-level locations for each category.

Security Implications

whereis carries minimal security risk on its own — it only reads directory listings in fixed, typically root-owned system locations and reports what it finds; it doesn’t execute anything. The one indirect consideration: because it only searches standard locations, it can give a false sense of completeness — a malicious or unofficial binary placed in a non-standard directory and prepended to PATH (a which-relevant PATH-hijacking concern) would not show up via whereis at all, since whereis never looks at PATH. Don’t rely on whereis for any kind of security audit of what will actually execute — that’s which -a and a careful look at $PATH, not whereis.

Compatibility Across Distributions

whereis is part of util-linux, which is included by default on virtually all mainstream Linux distributions — Ubuntu, Debian, Fedora, RHEL/CentOS, Arch, openSUSE. Behavior is largely consistent since they share the same util-linux implementation, though the exact default directory list can vary slightly based on distribution packaging conventions (for example, whether /usr/local/man or /usr/local/share/man is included). BSD systems and macOS do not ship the same util-linux whereis — macOS has a much simpler built-in whereis with different (more limited) behavior, so don’t assume flag compatibility across platforms.

A Note on the -g and -u Flags in Practice

Two of the less commonly used flags deserve a slightly closer look because their behavior can be confusing the first time you try them.

-g tells whereis to interpret the given name as a glob pattern rather than a literal command name, which lets you search for a family of related tools in one pass:

$ whereis -g 'python3*'

This is handy when you’re not sure exactly which version-suffixed binaries (python3.10, python3.11, python3-config) exist on a system, without needing to enumerate them individually.

-u is designed for a slightly different purpose than a first read suggests: rather than searching for a specific missing category, it flags entries that have an unusual number of matches — by default, that means anything with fewer than one match in each category, though combined with -m, -s, or -b you can narrow which category’s absence counts as “unusual.” In practice this is most useful as a system-wide audit tool, run against a full listing of installed binaries, to surface packages that installed executables without accompanying documentation or source, which can be a useful signal when investigating whether a package install was incomplete or improperly packaged.

Understanding whereis’s Relationship to Package Managers

It’s worth being explicit about something that trips people up: whereis has no awareness of your package manager at all. It doesn’t know which package installed a given binary, and it can’t tell you whether a newer version is available. It purely reports what’s physically present in its configured search directories at the moment you run it. If what you actually need is “which package provides this file” or “is there an update available,” that’s a job for dpkg -S, apt list --installed, rpm -qf, or dnf provides, depending on your distribution’s packaging system — not whereis. Keeping this boundary clear avoids reaching for whereis when what you actually want is package-level metadata rather than filesystem location data.

When whereis Is the Wrong Tool

It’s worth being direct about the situations where whereis will actively mislead you if used as your only source of truth:

• If you need to know what will actually execute when you type a command (accounting for your personal PATH, aliases, and shell functions), which or type is correct — whereis ignores all of that.
• If you need to search for a file that isn’t a binary, source file, or manual page — a config file, a data file, an arbitrary document — whereis simply won’t find it, since those categories are outside its scope entirely. Use find or locate instead.
• If you’re auditing security-relevant executable resolution (checking for PATH hijacking, verifying exactly which binary a privileged process will run), whereis‘s fixed-directory search gives you no visibility into that risk at all.

Best Practices

• Use whereis -l once on any new or unfamiliar system to understand exactly which directories are being searched, before drawing conclusions from an empty result.
• Prefer which over whereis when the question is specifically “what will run” rather than “is this fully installed with docs.”
• Use -u for a quick audit of incomplete installs — binaries lacking manual pages, in particular, is a common finding worth investigating.
• Don’t rely on whereis for anything security-sensitive; it doesn’t reflect PATH-based resolution at all.
• Combine with man -w or manpath when man page results seem inconsistent with what man itself finds, since MANPATH customization can create a gap between the two.

Summary

whereis fills a specific niche: quickly reporting the binary, source, and manual page locations for a command from a fixed set of conventional system directories, independent of your personal PATH. It’s most useful for checking installation completeness — did a package bring its documentation along, is source available for inspection — rather than for answering “what will actually run,” which remains squarely which‘s job. Knowing the difference, and knowing that whereis never touches PATH, prevents a category of confusing “why did these two tools give different answers” moments.

References

• Linux man-pages project: man 1 whereis — https://man7.org/linux/man-pages/man1/whereis.1.html
• util-linux Project (Kernel.org) — https://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
• Ubuntu Manpage Repository — https://manpages.ubuntu.com/manpages/noble/en/man1/whereis.1.html