Glossary¶

anonymous memory¶

RAM used by the program that is not associated with any file (unlike the page cache), such as the heap, the stack, and other memory allocated directly by the program (e.g. via malloc()). Anonymous pages have no on-disk counterpart and must be written to swap memory if evicted. Exposed by psutil via the rss_anon field of Process.memory_info_ex() (total resident anonymous pages) and the anonymous field of Process.memory_maps() (per mapping). Anonymous regions are also visible in the path column of Process.memory_maps() as "[heap]", "[stack]", or an empty string.

available memory¶

The amount of RAM that can be given to processes without the system going into swap. This is the right field to watch for memory pressure, not free. free is often deceptively low because the OS keeps recently freed pages as reclaimable cache; those pages are counted in available but not in free. A monitoring alert should fire on available (or percent) falling below a threshold, not on free. See virtual_memory().

buffers¶

Kernel memory used to cache filesystem metadata such as superblocks, inodes, and directory entries. Distinct from the page cache, which caches file contents. Like the page cache, buffer memory is reclaimable: the OS can free it under memory pressure. Reported as the buffers field of virtual_memory() (Linux, BSD).

busy_time¶

A cumulative counter (milliseconds) tracking the time a disk device spent actually performing I/O, as reported in the busy_time field of disk_io_counters() (Linux and FreeBSD only). To use it, sample twice and divide the delta by elapsed time to get a utilization percentage (analogous to CPU percent but for disks). A value close to 100% means the disk is saturated.

See also

Real-time disk I/O percent recipe

context switch¶

Occurs when the CPU stops executing one process or thread for another. Frequent switching can indicate high system load or thread contention. See Process.num_ctx_switches() and cpu_stats() (ctx_switches field). A voluntary context switch occurs when a process gives up the CPU, usually because it’s waiting for something (I/O, a sleep, a mutex lock). High rates are normal for I/O-bound workloads (e.g. a web server) and usually point to I/O or locking as the bottleneck. An involuntary context switch occurs when the OS forcibly takes the CPU from the process. High rates mean the process has more work to do but is being kicked off the core. This usually indicates too many active threads/processes competing for too few CPU cores.

CPU affinity¶

A property of a process (or thread) that restricts which logical CPUs it is allowed to run on. For example, pinning a process to CPU 0 and CPU 1 prevents the OS scheduler from moving it to other cores. This could be useful, e.g., for benchmarking. See Process.cpu_affinity().

cumulative counter¶

A field whose value only increases over time (since boot or process creation) and never resets. Examples include cpu_times(), disk_io_counters(), net_io_counters(), Process.io_counters(), and Process.num_ctx_switches(). The raw value is rarely useful on its own; divide the delta between two samples by the elapsed time to get a meaningful rate (e.g. bytes per second, context switches per second).

file descriptor¶

An integer handle used by UNIX processes to reference open files, sockets, pipes, and other I/O resources. On Windows the equivalent are handles. Leaking file descriptors (opening without closing) eventually causes EMFILE / Too many open files errors. See Process.num_fds() and Process.open_files().

handle¶

On Windows, an opaque reference to a kernel object such as a file, thread, process, event or mutex. Handles are the Windows equivalent of UNIX file descriptors. Each open handle consumes a small amount of kernel memory. Leaking / unclosed handles eventually causes ERROR_NO_MORE_FILES or similar errors. See Process.num_handles().

hardware interrupt¶

A signal sent by a hardware device (disk controller, NIC, keyboard) to the CPU to request attention. Each interrupt briefly preempts whatever the CPU was doing. Reported as the interrupts field of cpu_stats() and irq field of cpu_times(). A very high rate may indicate a misbehaving device driver or a heavily loaded NIC. Also see soft interrupt.

heap¶

The memory region managed by the platform’s native C allocator (e.g. glibc’s malloc on Linux, jemalloc on FreeBSD, HeapAlloc on Windows). When a C extension calls malloc() and never calls free(), the leaked bytes show up here but are not always visible to Python’s memory tracking tools (tracemalloc, sys.getsizeof()) or RSS / VMS. heap_info() exposes the current state of the heap, and heap_trim() asks the allocator to release unused portions of it. Together they provide a way to detect memory leaks in C extensions that standard process-level metrics would otherwise miss.

involuntary context switch¶

See context switch.

ionice¶

An I/O scheduling priority that controls how much disk bandwidth a process receives. On Linux three scheduling classes are supported: IOPRIO_CLASS_RT (real-time), IOPRIO_CLASS_BE (best-effort, the default), and IOPRIO_CLASS_IDLE. See Process.ionice().

iowait¶

A CPU time field (Linux, SunOS, AIX) measuring time spent by the CPU waiting for I/O operations to complete. High iowait indicates a disk or network bottleneck. It is reported as part of cpu_times() but is not included in the idle counter. To get it as a percentage: psutil.cpu_times_percent(interval=1).iowait. Note that this is a CPU metric, not a disk metric: it measures how much CPU time is wasted waiting, not how busy the disk is. See also busy_time for actual disk utilization.

logical CPU¶

A CPU as seen by the operating system scheduler. On systems with hyper-threading each physical core exposes two logical CPUs, so a 4-core hyper-threaded chip has 8 logical CPUs. This is the count returned by cpu_count() (the default) and the number of entries returned by cpu_percent(percpu=True). See also physical CPU.

mapped memory¶

A region of a process’s virtual address space typically created via mmap(). Mappings can be file-backed (e.g. shared libraries, memory-mapped files) or anonymous. Each mapping has its own permissions and memory accounting fields (RSS, PSS, private / shared pages). See Process.memory_maps().

NIC¶

Network Interface Card, a hardware or virtual network interface. psutil uses this term when referring to per-interface network statistics. See net_if_addrs() and net_if_stats().

nice¶

A process priority value that influences how much CPU time the OS scheduler gives to a process. Lower nice values mean higher priority. The range is −20 (highest priority) to 19 (lowest) on UNIX; on Windows the concept maps to priority constants. See Process.nice().

page cache¶

RAM used to cache data of regular files on disk. When a process reads a file, the data stays in the page cache, and when it writes, the data is first stored in the cache before being written to disk. Subsequent reads or writes can be served from RAM without disk I/O, making access fast. The OS reclaims page cache automatically under memory pressure, so a large cache is healthy. Shown as the cached field of virtual_memory() on Linux/BSD.

page fault¶

An event that occurs when a process accesses a virtual memory page that is not currently mapped in physical RAM. A minor fault occurs when a page is already in physical RAM (e.g., in the page cache or other shared memory), but it’s not yet mapped into the process’s virtual address space, so no disk I/O is required (fast). A major fault requires reading the page from disk, and is significantly more expensive. Many major faults may indicate memory pressure or excessive swapping. See Process.page_faults().

peak_rss¶

The highest RSS value a process has ever reached since it started (memory high-water mark). Available via Process.memory_info() (BSD, Windows) and Process.memory_info_ex() (Linux, macOS). Useful for capacity planning and leak detection: if peak_rss keeps growing across successive runs or over time, the process is likely leaking memory. See also peak_vms.

peak_vms¶

The highest VMS value a process has ever reached since it started. Available via Process.memory_info_ex() (Linux) and Process.memory_info() (Windows). On Windows this maps to PeakPagefileUsage (peak private committed memory), which is not the same as UNIX VMS. See also peak_rss.

physical CPU¶

An actual hardware CPU core on the motherboard, as opposed to a logical CPU. A single physical core may appear as multiple logical CPUs when hyper-threading is enabled. The physical count is returned by cpu_count(logical=False).

private memory¶

Memory pages not shared with any other process, such as the heap, the stack, and other allocations made directly by the program, e.g. via malloc(). USS, returned by Process.memory_footprint(), measures exactly the private memory of a process, that is the bytes that would be freed if the process exited. At a per-mapping level, the private_clean and private_dirty fields of Process.memory_maps() (Linux) and the private field (FreeBSD) break it down further.

PSS¶

Proportional Set Size, the amount of RAM used by a process, where shared memory pages are divided proportionally among all processes that map them. PSS gives a fairer per-process memory estimate than RSS when shared libraries are involved. Available on Linux via Process.memory_footprint().

resource limit¶

A per-process cap on a system resource enforced by the kernel (POSIX RLIMIT_* constants). Each limit has a soft value (the current enforcement threshold, which the process may raise up to the hard limit) and a hard value (the ceiling, settable only by root). Common limits include RLIM_INFINITY (open file descriptors), RLIMIT_AS (virtual address space), and RLIMIT_CPU (CPU time in seconds). See Process.rlimit().

RSS¶

Resident Set Size, the amount of physical RAM currently used by a process. This includes shared memory pages. It is the most commonly reported memory metric (shown as RES in top), but can be misleading because shared memory is counted in full for each process that maps it. See Process.memory_info().

shared memory¶

Memory pages mapped by more than one process at the same time. The most common example is shared libraries (e.g. libc.so): the OS loads them once and lets every process that needs them map the same physical pages, saving RAM. Shared pages are counted in full in RSS for every process that maps them. PSS corrects for this by splitting each shared page proportionally among the processes that use it. See also private memory.

Exposed by psutil as the shared field of virtual_memory() and Process.memory_info() (Linux), the rss_shmem field of Process.memory_info_ex() (Linux), and the shared_clean / shared_dirty fields of Process.memory_maps() (Linux).

soft interrupt¶

Deferred work scheduled by a hardware interrupt handler to run later in a less time-critical context (e.g. network packet processing, block I/O completion). Using soft interrupts lets the hardware interrupt return quickly while the heavier processing happens shortly after. Reported as the soft_interrupts field of cpu_stats(). A high rate usually points to heavy network or disk I/O throughput rather than a hardware problem.

swap memory¶

Disk space used as an extension of physical RAM. When the OS runs out of RAM, it moves memory to disk to free space (swap-out), and moves it back into RAM (swap-in) when a process needs it. If RAM is full, the OS may first swap out other pages to make room. Swap prevents out-of-memory crashes, but is much slower than RAM, so heavy swapping can significantly degrade performance. See swap_memory() and swap activity recipe.

swap-in¶

Memory moved from disk (swap) back into RAM. Reported as the sin cumulative counter of swap_memory(). A non-zero sin rate usually means the system is bringing memory back into RAM for processes to use. See also swap-out.

swap-out¶

Memory moved from RAM to disk (swap). Reported as the sout cumulative counter of swap_memory(). A non-zero sout rate indicates memory pressure: the system is running low on RAM and must move data to disk, which can slow performance. See also swap-in.