LinuxHandbook/article/linux-pgrep-tutorial.md at main · fhmio/LinuxHandbook

title

Linux Command Tutorial: pgrep

date

2026-09-12 00:00:00 +0000

1. Introduction

Upstream: procps-ng 4.0.4 | POSIX: De-facto Standard (Not POSIX standardized) | Safety Tier: safe-read-only | Scope: process-search

pgrep searches the currently running processes and outputs the process IDs (PIDs) matching specified selection criteria to standard output. It eliminates the need for fragile pipelines like ps aux | grep name | awk '{print $2}'.

Upstream Project & Provenance: Maintained within procps-ng (procps-ng).
Portability & Standards Baseline: pgrep is an industry-standard UNIX utility originating from Solaris; not defined in POSIX.1-2024.
Target Research Implementation: Audited against procps-ng 4.0.4 (pgrep(1)).
Applicability & Lifecycle: The preferred tool for finding process IDs based on executable names, arguments, usernames, or session groups.

2. Syntax and Command Model

2.1 Canonical Synopsis

pgrep [options] pattern

2.2 Execution Model & Extended Regular Expressions

pattern is evaluated as an Extended Regular Expression (ERE).
By default, pgrep matches against the basename of the executable (from /proc/[pid]/stat).
If -f (full) is passed, pgrep matches against the complete command line and arguments (from /proc/[pid]/cmdline).
Output consists of matching PIDs separated by newlines (or custom delimiter via -d).

3. Options

3.1 Primary Flags

Flag	Description	Default	Upstream Note
`-l`	List the process name as well as the process ID.	PID only	Convenient for verification
`-a`	List the full command line arguments as well as the PID.	PID only	Avoids ambiguity
`-f`	Match pattern against full command line arguments, not just basename.	Basename	Crucial for scripts
`-x`	Exact match: require pattern to match the entire name or command line.	Substring	Prevents false positives
`-u user`	Match only processes owned by effective user ID or username.	All users	User filtering
`-U user`	Match only processes owned by real user ID or username.	All users	User filtering
`-o`	Select only the oldest (least recently started) matching process.	All matches	Singleton selection
`-n`	Select only the newest (most recently started) matching process.	All matches	Singleton selection
`-c`	Suppress normal output; print a count of matching processes.	Print PIDs	Counting instances
`-d delim`	Set string used to separate PIDs in output (e.g. `,`).	Newline `\n`	Pipeline friendly

4. Basic Usage

4.1 Quick-Reference Cheatsheet Card

Operation	Command	Notes
Find PIDs by name	`pgrep nginx`	Substring match against binary name
Exact name match	`pgrep -x sshd`	Avoids substring false positives
List PID and command name	`pgrep -l nginx`	Prints PID and short binary name
Match full command line	`pgrep -fa "app.py"`	Inspects argument vector and prints full command
Filter by username	`pgrep -u www-data php-fpm`	Restricts search to user's processes
Count matching processes	`pgrep -c nginx`	Returns numeric count of matches
Comma-delimited list	`pgrep -d, worker`	Generates PID list for `top -p` or `kill`

4.2 Finding PIDs by Name

pgrep nginx

4512
4513
4514

4.3 Listing PIDs Alongside Binary Names

pgrep -l sshd

1105 sshd
4912 sshd

5. Practical Operations

5.1 Exact Matching to Avoid False Positives (`-x`)

When searching for a service named sh, standard pgrep sh matches sshd, bash, ssh-agent, etc.:

pgrep -x sh

Technical Analysis: -x requires the pattern to match the entire process name from start to finish (^pattern$), matching strictly /bin/sh processes.

5.2 Searching Python and Java Scripts by Full Arguments (`-f`)

Because Python processes appear in /proc as python3, searching for worker.py with standard pgrep matches nothing:

pgrep -fa "worker.py"

12402 python3 /opt/app/worker.py --concurrency=4

-f inspects the full argument vector, while -a prints the arguments for visual confirmation.

5.3 Counting Active Worker Instances

Checking how many worker processes are currently alive:

pgrep -c -u www-data php-fpm

5.4 Formatting Comma-Delimited PIDs for Other Utilities

Passing PIDs directly into tools like top or strace:

top -p $(pgrep -d, nginx)

6. Advanced Usage

6.1 Avoiding the Self-Matching Trap of `ps | grep`

Tip

No Self-Matching: Unlike ps aux | grep nginx (which matches the running grep process itself unless filtered), pgrep automatically excludes its own PID from search results.

7. Exit Status, Environment, and Configuration

7.1 Exit Status Codes

Exit Code	Meaning
`0`	One or more matching processes were found.
`1`	No matching processes were found.
`2`	Syntax error in the command-line options.
`3`	Fatal error (e.g. out of memory).

This makes pgrep ideal for shell conditional tests:

if pgrep -x nginx > /dev/null; then
    echo "Nginx is running"
fi

8. Safety, Security, and Portability

8.1 Truncated Comm Names

Note

Linux limits the kernel task comm field (/proc/[pid]/comm) to 15 characters. If an executable name exceeds 15 characters, standard pgrep matches against the truncated name. Pass -f to match against the full command line from /proc/[pid]/cmdline.

9. Best Practices

Always Use -x When Matching Standard Utilities:
- Guidance: Write pgrep -x <name> when matching well-known binaries.
- Authoritative Justification: Prevents substring collisions with unrelated daemons.
Use -f for Interpreted Scripts (Python, Node, Java):
- Guidance: Pass -f when searching for script paths.
- Authoritative Justification: The binary name of interpreted scripts is the interpreter (python3), not the script name.
Use -c for Instance Monitoring:
- Guidance: Check pool concurrency using pgrep -c.
- Authoritative Justification: Avoids piping into wc -l.

References

procps-ng pgrep(1) Manual: https://man7.org/linux/man-pages/man1/pgrep.1.html
Linux /proc/[pid]/status Documentation: https://docs.kernel.org/filesystems/proc.html

FilesExpand file tree

linux-pgrep-tutorial.md

Latest commit

History