VMware ESXi and vSphere Cluster Management

Linux whereis Command: Find Binary, Source, and Manual Files

Learn how to use Linux whereis to locate executable binaries, source code, and manual pages, with examples, options, custom paths, and troubleshooting.

The Linux whereis command locates conventional files associated with a program name. It can report an executable binary, installed source code, and manual-page files. For example, it can help you determine where bash is installed and where its documentation is stored.

whereis searches a restricted set of conventional directories. It does not scan the entire filesystem and it does not simply search every directory listed in the shell's PATH variable.

What whereis Finds

A binary is an executable program file. Common binary directories include /bin, /usr/bin, /sbin, and /usr/sbin. A source file is human-readable program code; source packages are often not installed on a normal runtime system. A manual page, or man page, is system documentation read with the man command.

By default, whereis may search for all three categories. Its search directories are predefined and limited. Therefore, a program can be installed and usable while still being absent from ordinary whereis output if it is stored in a nonstandard directory.

Basic Syntax and Output

whereis [options] name

The argument is normally a command or program name, without its full path. The output begins with the queried name, followed by zero or more matching paths.

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

In this example, /usr/bin/grep is an executable match. The file ending in .1.gz is a compressed manual page in section 1.

Reading whereis Results

File type — Typical directories — Example path pattern

User command binaries — /bin, /usr/bin — /usr/bin/name

Administrative command binaries — /sbin, /usr/sbin — /usr/sbin/name

Manual pages — /usr/share/man/man1, /usr/share/man/man8 — /usr/share/man/man1/name.1.gz

Program source — commonly source directories such as /usr/src when included in the configured search — /usr/src/name/...

Manual-page filenames usually include a numbered section suffix. Section 1 commonly contains user commands, while section 8 commonly contains administrative commands. A suffix such as .1 or .8 identifies the section. Many distributions compress man pages, so a filename may end in .gz, for example systemctl.1.gz.

Source paths appear only when matching source files are installed in directories searched by whereis. The absence of a source path is normal on systems where only compiled software and documentation are installed.

Core Usage Examples

Locate a networking utility

$ whereis netstat
netstat: /bin/netstat /usr/share/man/man8/netstat.8.gz

This example shows an executable in /bin and a compressed section-8 manual page. On many current installations, netstat is not installed by default, so the exact result can be empty or different. Paths vary by distribution and installed packages.

Look up common utilities

$ whereis ls
a$ whereis bash
bash: /usr/bin/bash /usr/share/man/man1/bash.1.gz
$ whereis grep
 grep: /usr/bin/grep /usr/share/man/man1/grep.1.gz

Each lookup reports the name followed by its matches. A single program can have multiple executable or documentation paths, for example because compatibility links, alternative installations, or several manual-page sections are present.

Query several names at once

$ whereis bash python3 systemctl
bash: /usr/bin/bash /usr/share/man/man1/bash.1.gz
python3: /usr/bin/python3 /usr/share/man/man1/python3.1.gz
systemctl: /usr/bin/systemctl /usr/share/man/man1/systemctl.1.gz /usr/share/man/man8/systemctl.8.gz

One invocation can accept multiple program names. Each name receives its own output line.

Search-Category Options

Category options change which result types are displayed. Without them, the command normally considers binaries, manuals, and source files.

Option — Search category or behavior — Typical use — Example

-b — Binary files — Find executable matches only — whereis -b ls

-m — Manual pages — Find installed documentation only — whereis -m grep

-s — Source files — Find installed source matches only — whereis -s bash

-u — Unusual or incomplete results — Report names missing expected matches in selected categories — whereis -u -m customtool

-B — Custom binary directories — Search a known nonstandard binary location — whereis -B /opt/tools/bin -f customtool

-M — Custom manual directories — Search documentation installed outside standard locations — whereis -M /opt/tools/man -f customtool

-S — Custom source directories — Search a known source tree — whereis -S /opt/tools/src -f customtool

-f — Ends custom directory lists — Marks the point where program names begin — whereis -B /opt/tools/bin -f customtool

Binary-only searches with -b

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

This displays binary matches and excludes manual-page and source matches. Compare it with the shell's resolution of the command:

$ command -v ls
/usr/bin/ls

command -v answers which executable the current shell would run, based primarily on shell rules and PATH. It is not a replacement for all of whereis's file categories.

Manual-only searches with -m

$ whereis -m grep
grep: /usr/share/man/man1/grep.1.gz
$ man grep

The returned path identifies an installed manual page that can normally be opened with man grep.

Source-only searches with -s

$ whereis -s bash
bash:

An empty result after the name means no matching source file was found in the source directories being searched. This does not indicate that the executable is missing.

Combining category options

$ whereis -b -m systemctl
systemctl: /usr/bin/systemctl /usr/share/man/man1/systemctl.1.gz /usr/share/man/man8/systemctl.8.gz

Combining -b and -m requests binaries and manuals while excluding source results. Use more than one category option when you need a specific combination.

Reporting Incomplete Results with -u

The -u option reports names with unusual or incomplete results according to the selected search categories. It is useful for checking whether expected files are missing, such as a command with no installed manual page.

$ whereis -m -u customtool
customtool:

With -m, the check focuses on the manual-page category. A missing manual page can be reported even when the executable exists. Similarly, selecting another category changes what counts as incomplete for that lookup. Interpret -u together with the category options you supplied.

Searching Custom Locations

Use -B for binary directories, -M for manual-page directories, and -S for source directories. Each custom directory list must be followed by -f; only after -f does whereis treat the remaining arguments as program names.

$ whereis -B /opt/tools/bin -f customtool
customtool: /opt/tools/bin/customtool
$ whereis -M /opt/tools/man -f customtool
customtool: /opt/tools/man/man1/customtool.1.gz

Custom locations are useful for software installed under /opt, an organization-specific directory, or another path outside the normal defaults. Multiple directories can be supplied for a category before -f, according to the implementation documented by man whereis.

whereis Compared with Other Lookup Tools

Tool — Best for — Search scope — Key limitation

whereis — Finding conventional binary, source, and manual files — Restricted standard directories or selected custom directories — Not a complete filesystem search

command -v — Finding the command path selected by the current shell — Shell command resolution and PATH — Usually reports one executable and not manuals or source

type — Explaining shell resolution — Aliases, functions, builtins, and PATH commands — Describes shell behavior rather than general file locations

which — A traditional executable lookup — Usually searches PATH — Behavior varies and it may not reveal aliases or functions reliably

find — Searching for files by path, name, type, or other predicates — Direct filesystem traversal of chosen directories — Can be slower and requires a search location

locate — Fast name searches — A prebuilt file index — Results can be stale or unavailable if the index is missing

Package-manager file query — Identifying files installed by a package — Package database or repository metadata — Syntax varies by distribution and may not include unmanaged files

Choose whereis when you want a quick overview of conventional program files and documentation. Choose command -v or type -a when the question is what the current shell will execute. Choose find or locate for broader filename searches. Use a package manager when you need to determine which package owns a file or which files a package installed.

Important Limitations

  • It is not a full filesystem search. A result does not prove that no other copy exists elsewhere.
  • It does not simply search PATH. A command in a custom PATH directory can be executable by the shell but absent from default whereis results.
  • Empty results can be normal. The software, source package, or man-page package may not be installed, or files may be outside configured search paths.
  • Configuration files are not a primary result category. Use package-manager file listings or find when looking for files such as those under /etc.
  • Distribution layouts differ. Some systems merge directories such as /bin into /usr/bin, and package contents vary.

Troubleshooting whereis Output

No paths are returned

Output containing only the name, such as customtool:, can mean the program is not installed, the name does not match the installed file, or the files are outside the default search directories.

$ command -v customtool
$ find /opt /usr/local -name customtool -type f 2>/dev/null

If you know the installation directory, use a custom search:

$ whereis -B /opt/tools/bin -f customtool

An executable is found but no manual page is listed

Documentation may be packaged separately, omitted by the administrator, provided only through customtool --help, or stored in a nonstandard manual directory.

$ customtool --help
$ whereis -M /opt/tools/man -f customtool

A package-manager file query can show whether the installed package contains a manual page.

whereis differs from which or command -v

whereis can show several related files, while the shell may resolve an alias, function, builtin, or a command found through PATH. Inspect shell resolution explicitly:

$ type -a program_name
$ command -v program_name

Differences can also indicate that the program is installed in a custom directory omitted from whereis's defaults.

Looking for configuration files

Use a package file listing, the program's documentation, or a targeted filesystem search instead of relying on whereis:

$ find /etc -name '*program_name*' 2>/dev/null

Search only directories you are permitted to inspect, and consult the program documentation because configuration filenames and locations vary.

Exam-Relevant Notes

  • whereis [options] name takes a program name and reports matching conventional paths.
  • -b, -m, and -s select binaries, manual pages, and source files.
  • -u reports unusual or incomplete results relative to the selected categories.
  • -B, -M, and -S define custom category directories; terminate those directory lists with -f.
  • A missing path does not necessarily mean the program is absent; the relevant package or nonstandard directory may be the reason.
  • Use command -v for the current shell's executable resolution and find for a broad filesystem search.

Quick Reference

whereis name                    # standard lookup
whereis -b name                 # binary matches only
whereis -m name                 # manual-page matches only
whereis -s name                 # source matches only
whereis -b -m name              # binary and manual matches
whereis -u -m name              # unusual or missing manual result
whereis -B /opt/tools/bin -f customtool
whereis -M /opt/tools/man -f customtool
command -v name                 # shell-resolved executable
man whereis                      # system-specific details

For a broader lesson on this command, return to the Linux whereis command guide.