psutil: Cross-Platform Process and System Monitoring for Python

What psutil Exposes and Who Uses It

psutil is a cross-platform Python library for retrieving information about running processes and system resource utilization. The README describes its scope as CPU, memory, disks, network, and hardware sensors, and notes that it is useful for system monitoring, profiling, limiting process resources, and managing running processes. It re-implements the data exposed by command-line tools such as ps, top, free, netstat, and iotop in a Python API that works without spawning subprocesses or parsing their text output.

The library targets engineers writing monitoring agents, resource-limited process launchers, diagnostic scripts, and automation tools that need portable access to OS-level data. The README states it runs on Linux, Windows, macOS, FreeBSD, OpenBSD, NetBSD, Sun Solaris, and AIX. That coverage means one code path can serve a Linux container and a Windows service monitor without conditional imports.

According to the README's adoption section, psutil is among the top 100 most-downloaded packages on PyPI with 390 million downloads per month and over 780,000 GitHub repositories depending on it. The README also links to a dedicated adoption page at psutil.io/adoption listing known users. These figures reflect the library's position as a standard dependency in the monitoring and system administration space.

How psutil Bridges Python to the Operating System

psutil is partly written in C. The setup.py file at the repository root builds a platform-specific C extension that calls native OS APIs directly: it uses procfs on Linux, sysctl on BSD variants, and Win32 performance counter APIs on Windows. The Python layer wraps those C calls into named tuples and Python objects with consistent attribute names across platforms. This design means that psutil.cpu_percent() on Linux reads /proc/stat through a C wrapper; on macOS it calls Mach host statistics; on Windows it calls Win32 performance counters. The Python caller sees the same function signature regardless of the underlying OS.

Named tuples are the standard return type across the API. A call to psutil.virtual_memory() returns an svmem object with fields including total, available, percent, used, and free. A call to psutil.disk_partitions() returns a list of sdiskpart objects, each with device, mountpoint, fstype, and opts fields. This consistency allows inspection scripts to be platform-independent at the Python level, even though the C extension is platform-specific. The pyproject.toml at the repository root lists setuptools as the build backend, with a minimum version requirement designed to support Python 3.8.

Installing psutil and Making the First API Calls

The README gives one installation command:

pip install psutil

This compiles the C extension automatically using the installed C compiler. On Linux and macOS, a compiler must be present; on Windows, pre-built wheels are available on PyPI. The README directs readers to psutil.io/install for platform-specific details when the standard pip install does not work.

After installation, process queries work through the psutil.Process class. Passing a PID returns a handle for that process:

>>> import psutil
>>> p = psutil.Process(7055)
>>> p.name()
'python3'
>>> p.cpu_percent(interval=1.0)
12.1

System-wide CPU and memory queries do not need a Process object:

>>> psutil.cpu_percent(interval=1, percpu=True)
[4.0, 6.9, 3.7, 9.2]
>>> psutil.virtual_memory()
svmem(total=10367352832, available=6472179712, percent=37.6, used=8186245120, free=2181107712, ...)

To iterate over all running processes and inspect their PID and name, the README shows:

>>> for p in psutil.process_iter(['pid', 'name']):
...     print(p.pid, p.name())

The interval parameter in cpu_percent causes the call to block for that many seconds before returning the measured value. Passing interval=None returns the value since the last call, which requires a prior call to initialize the counter.

Querying Disks, Network, and Hardware Sensors

Beyond processes and CPU, psutil covers disk partitions, I/O counters, network interfaces, open connections, and hardware sensors. The README example for disk partitions:

>>> psutil.disk_partitions()
[sdiskpart(device='/dev/sda1', mountpoint='/', fstype='ext4', opts='rw,nosuid'),
 sdiskpart(device='/dev/sda2', mountpoint='/home', fstype='ext', opts='rw')]

For network I/O per interface:

>>> psutil.net_io_counters(pernic=True)
{'eth0': netio(bytes_sent=485291293, bytes_recv=6004858642, ...),
 'lo': netio(bytes_sent=2838627, bytes_recv=2838627, ...)}

Sensor access returns temperature readings when the platform supports them. The README example shows coretemp readings on Linux through psutil.sensors_temperatures(). Battery state is accessible through psutil.sensors_battery() with fields for percent charge, seconds remaining, and whether the system is plugged in.

These sensor APIs are not available on all platforms. The README mentions platform support at a high level but does not enumerate per-call availability. The API reference at psutil.io/api documents which attributes raise AccessDenied or return partial data on each supported platform, and consulting it before writing code that depends on sensor or battery APIs prevents surprises in production.

Where psutil Cannot Help You

psutil is a read and query library. It does not provide callbacks or event hooks for monitoring changes as they occur: there is no notification for when a new process starts, when a network connection opens, or when disk usage crosses a threshold. Building a monitoring system that reacts to state changes requires polling on a timer loop; psutil supplies the data for each poll but does not provide the loop or any callback mechanism.

The library exposes process attributes and a limited write surface. You can terminate a process, send signals, change niceness, and set resource limits on Unix. You cannot attach to a process for debugging, inject code, or snapshot process memory in a format suitable for reverse engineering or live patching. That work requires platform-specific APIs that psutil does not wrap.

Not all attributes are available on every platform. Network connection queries require elevated privileges on macOS to see connections for processes owned by other users. On some BSD variants, certain memory fields return zero or raise AccessDenied for non-root calls. Developers targeting non-Linux platforms should verify which calls behave correctly with the privileges available in their deployment environment.

psutil vs the Standard Library: Two Different Depths

Python's standard library includes the os and resource modules, which expose basic process control and resource limits on Unix, and the subprocess module for launching and observing child processes. The difference from psutil is depth and portability: os.getpid() returns the current process ID; psutil.Process(pid).connections() returns the TCP and UDP connections that process has open. The os module cannot enumerate all running processes, report their memory consumption in detail, or read hardware sensor data.

The comparison to subprocess involves a different use case: subprocess is for launching and controlling processes you start yourself; psutil is for inspecting processes that already exist, including those you did not start. The two libraries are complementary in monitoring scripts that both spawn background workers and track their resource use over time. Neither the os module nor subprocess provides cross-platform access to CPU frequency, battery state, or disk partition details; psutil fills that gap.

Maintenance and BSD-3-Clause Licence

The last push to the repository was on 2026-09-14. The HISTORY.rst file at the repository root records changes across the release history. psutil is distributed as a Python package under BSD-3-Clause licence terms. BSD-3 permits commercial use, distribution, and modification without requiring source disclosure. The three conditions are: preserve the copyright notice, do not use contributor names for endorsement without permission, and reproduce the licence text in binary distributions.

The pyproject.toml file uses PEP 735 dependency groups to separate test, lint, and documentation dependencies from the published package. The published package has no Python-level dependencies beyond the C extension it builds from source. The Makefile includes a target structure for development tasks including clean, build, and test, using GNU make syntax with BSD make compatibility notes in the comments.

Editorial conclusion

psutil belongs in any Python codebase that needs portable access to process or system data without shelling out to ps, top, or netstat. It is not the right choice for event-driven monitoring (there are no callbacks for process start or connection events) or for write-heavy process control beyond signals and resource limits. Before deploying on FreeBSD, NetBSD, or AIX targets, check psutil.io/api for which attributes are available on those platforms, since coverage is not uniform across all supported systems.

Frequently asked questions

Official sources

1. giampaolo/psutil on GitHub
2. Issues
3. License: BSD-3-Clause
4. Project website
5. README