pgrep

Look up processes based on name and other attributes.

Description

Searches the process table and reports process IDs of processes matching the given criteria. By default, matches the pattern against process names (the comm field). With -f, matches against the full command line.

Inputs

/proc/[pid]/stat – process name (comm), PID, PPID, process group, session, tty, start time
/proc/[pid]/status – real/effective UID, real GID
/proc/[pid]/cmdline – full command line
/proc/uptime – system uptime (for --older calculation)

Arguments

Positional

Argument	Description
`pattern` (optional)	Extended regular expression to match process names (or full command lines with `-f`). Required unless at least one filter flag is specified.

Matching options

Flag	Description
`-f, --full`	Match against the full command line instead of just the process name
`-i, --ignore-case`	Case-insensitive matching
`-x, --exact`	Require an exact match (anchors the pattern with `^...$`)
`-v, --inverse`	Negate the matching: select non-matching processes

Selection filters

Flag	Description
`-n, --newest`	Select only the most recently started matching process
`-o, --oldest`	Select only the least recently started matching process
`-O, --older SECS`	Select only processes older than SECS seconds
`-P, --parent PPID,...`	Match only processes whose parent PID is in the list
`-g, --pgroup PGRP,...`	Match only processes in the given process group IDs (0 means pgrep’s own process group)
`-G, --group GID,...`	Match only processes whose real group ID is in the list
`-s, --session SID,...`	Match only processes whose session ID is in the list (0 means pgrep’s own session)
`-t, --terminal TERM,...`	Match only processes whose controlling terminal is in the list
`-u, --euid UID,...`	Match only processes whose effective user ID is in the list (accepts names or numeric IDs)
`-U, --uid UID,...`	Match only processes whose real user ID is in the list (accepts names or numeric IDs)
`-r, --runstates STATE,...`	Match only processes in the given run states (R, S, D, Z, T, etc.)

Output options

Flag	Description
`-c, --count`	Print only a count of matching processes instead of PIDs
`-d, --delimiter DELIM`	String to use between PIDs in output (default: newline)
`-l, --list-name`	Print PID and process name for each match
`-a, --list-full`	Print PID and full command line for each match

Behavior

Iterates over all processes in /proc, applies the specified filters, and matches the pattern (if given) against the process name or full command line.

Key behaviors:

pgrep always excludes its own PID from results.
Results are sorted by PID.
Multiple filter flags are combined with AND logic: a process must satisfy all specified filters.
A pattern is optional when at least one filter flag is provided.
With --newest or --oldest, only a single process (the one with the most recent or earliest start time among all matches) is reported.
Process matching logic is shared with pkill via the procutils-common library crate.

Exit codes

Code	Meaning
0	One or more processes matched
1	No processes matched
2	Syntax error (invalid arguments)
3	Fatal error

Divergences from procps-ng

Behaviour matches procps-ng for the supported flag set; some procps-ng features are not yet implemented:

-F pidfile — read PIDs from a file. The mutual exclusion between -F and -p is therefore also absent.
--env VAR[=value] — match against a process’s environment.
-Q (shell-quoted output) — wrap names containing spaces in single quotes for safe shell consumption.
The warning emitted when the pattern is longer than 15 characters without -f (since comm is truncated to 15 characters by the kernel, a longer pattern can never match without -f).

Error messages for invalid arguments use different wording.

Keyboard shortcuts

procutils