psutil: Python System and Process Utilities

The project uses self-hosted web fonts (latin subset) for its UI. These fonts are integrated into the project's styling via the ../css/fonts.css file.

The following font families are used:

• Inter
• JetBrains Mono
• Merriweather

All fonts are licensed under the SIL Open Font License 1.1.

Free-threaded Python (introduced in Python 3.13) refers to Python builds where the GIL (Global Interpreter Lock) is disabled. This allows multiple threads to execute Python bytecodes in true parallel, which is beneficial for CPU-bound applications on multi-core processors.

Because psutil contains C extensions, it requires specific wheels to run on these builds. psutil 7.1.2+ provides these wheels, allowing users to run psutil in a no-GIL environment without manual compilation.

Context switches occur when the CPU stops executing one process/thread for another. Use Process.num_ctx_switches() or cpu_stats().ctx_switches to monitor them:

• Voluntary context switches: Occur when a process gives up the CPU (e.g., waiting for I/O or a lock). High rates in I/O-bound workloads are normal.
• Involuntary context switches: Occur when the OS forcibly takes the CPU from a process. High rates indicate too many active threads/processes competing for too few CPU cores.

psutil.Process instances are hashable, meaning they can be compared for equality and used in sets or as dictionary keys. Equality is determined by both the PID and the process creation time, which prevents confusion if a PID is reused by the kernel. This is useful for diffing process snapshots.

>>> before = set(psutil.process_iter())
>>> # ... some time passes ...
>>> after = set(psutilutil.process_iter())
>>> new_procs = after - before  # processes spawned in between

When monitoring process memory, choose the metric that fits your needs:

• RSS (Resident Set Size): Total physical RAM currently used by a process, including shared memory. It can be misleading because shared memory is counted in full for every process using it.
• VMS (Virtual Memory Size): Total virtual address space reserved, including mapped files and swap. Usually much larger than RSS.
• PSS (Proportional Set Size): A fairer estimate than RSS; it divides shared memory pages proportionally among all processes using them (Linux only).
• USS (Unique Set Size): The most accurate single-process metric. It represents the private memory that would be freed if the process exited, excluding all shared memory. Available via Process.memory_footprint() on Linux, macOS, and Windows.

To measure a process's memory usage, choose based on your requirements for accuracy versus performance:

• Process.memory_info(): Returns rss (Resident Set Size). It is fast but includes shared libraries. If multiple processes use the same library, that library's size is counted in the rss of every process.
• Process.memory_footprint(): Returns uss (Unique Set Size), representing the process's private memory. This is the amount of memory that would be freed if the process were terminated. It is more accurate for determining actual per-process impact but is substantially slower and requires higher privileges.

Note: On Linux, memory_footprint() also returns pss (Proportional Set Size) and swap.

In psutil 2.0.0+, the timeout parameter for CPU percent functions now defaults to 0.0 instead of 0.1. This prevents accidental blocking/sleeping when iterating over many processes.

Affected functions:

• Process.cpu_percent
• psutil.cpu_percent
• psutil.cpu_times_percent

# This will be slow if timeout is not specified as 0.0
for p in psutil.process_iter():
    print(p.cpu_percent())

Swap memory is disk space used as RAM extension. Monitor swap_memory() for:

• swap-in (sin): Memory moved from disk to RAM.
• swap-out (sout): Memory moved from RAM to disk. High sout rates indicate memory pressure.

Thrashing occurs when high, sustained rates of both sin and sout are observed, meaning the system is spending more time moving memory than doing actual work, leading to unresponsiveness.