psutil

Cross-platform library for retrieving information on running processes and system utilization (CPU, memory, disks, network, sensors) in Python.

Package Information

Name: psutil
Language: Python
Installation: pip install psutil
Platforms: Linux, Windows, macOS, FreeBSD, OpenBSD, NetBSD, AIX, Solaris

Core Imports

import psutil
from psutil import Process, Popen

{ .api }

Basic Usage

import psutil

# System info
print(f"CPU count: {psutil.cpu_count()}")
print(f"Memory: {psutil.virtual_memory()}")
print(f"Boot time: {psutil.boot_time()}")

# Process info
p = psutil.Process()  # Current process
print(f"PID: {p.pid}")
print(f"Name: {p.name()}")
print(f"CPU percent: {p.cpu_percent()}")

# List all processes
for proc in psutil.process_iter(['pid', 'name', 'cpu_percent']):
    print(proc.info)

{ .api }

Architecture

psutil provides two main API categories:

Process Class

The Process class represents individual system processes and provides comprehensive process management and monitoring capabilities. Processes can be accessed by PID or iterated over.

System Functions

Module-level functions provide system-wide information about CPU, memory, disk, network, and sensors.

Core Capabilities

Process Management

• Process Information: Get detailed process metadata including PID, name, status, parent/children relationships
• Resource Monitoring: Monitor CPU usage, memory consumption, I/O statistics, and file handles
• Process Control: Suspend, resume, terminate, and kill processes with proper signal handling
• Platform Features: Access platform-specific attributes like ionice, rlimit, and process priorities

See: Process Documentation

System Information

• CPU Monitoring: CPU count, usage statistics, frequency, and load averages
• Memory Stats: Virtual memory, swap usage, and memory mapping information
• Disk Operations: Disk usage, partitions, and I/O counters for storage devices
• Network Stats: Network interface information, connections, and I/O statistics

See: System Information Documentation

Hardware Sensors

• Temperature Monitoring: CPU and system component temperatures
• Fan Control: Fan speed monitoring across hardware components
• Battery Information: Battery status, charge level, and power management

See: Sensors Documentation

Constants and Exceptions

• Platform Constants: Operating system and platform identification
• Status Constants: Process and connection states and statuses
• Exception Handling: Comprehensive exception hierarchy for error management

See: Constants | Exceptions

Key API Examples

Process Iteration

# Iterate over all processes with specific attributes
for proc in psutil.process_iter(['pid', 'name', 'cpu_percent']):
    try:
        print(f"{proc.info['pid']}: {proc.info['name']} ({proc.info['cpu_percent']}%)")
    except (psutil.NoSuchProcess, psutil.AccessDenied):
        pass

{ .api }

System Monitoring

# Get system-wide CPU and memory usage
cpu_percent = psutil.cpu_percent(interval=1)
cpu_times_percent = psutil.cpu_times_percent(interval=1)  # Detailed CPU time breakdown
memory = psutil.virtual_memory()
print(f"CPU: {cpu_percent}%, Memory: {memory.percent}%")
print(f"CPU User: {cpu_times_percent.user}%, System: {cpu_times_percent.system}%")

{ .api }

Process Control

# Find and terminate processes by name
for proc in psutil.process_iter(['pid', 'name']):
    if 'python' in proc.info['name']:
        proc.terminate()  # or proc.kill() for force

{ .api }

Error Handling

try:
    p = psutil.Process(1234)
    print(p.name())
except psutil.NoSuchProcess:
    print("Process not found")
except psutil.AccessDenied:
    print("Permission denied")
except psutil.ZombieProcess:
    print("Process is zombie")

{ .api }

System Overview and Testing

# Quick system overview (similar to ps/top command)
psutil.test()  # Prints comprehensive system information to stdout

# Version information
print(f"psutil version: {psutil.__version__}")

# Platform-specific features
if psutil.WINDOWS:
    # Windows service management
    for service in psutil.win_service_iter():
        if service.status() == 'running':
            print(f"Running service: {service.name()} - {service.display_name()}")
            
elif psutil.LINUX:
    # Linux-specific resource limits
    p = psutil.Process()
    if hasattr(psutil, 'RLIMIT_NOFILE'):
        soft, hard = p.rlimit(psutil.RLIMIT_NOFILE)
        print(f"File descriptor limits: soft={soft}, hard={hard}")

{ .api }

Platform Compatibility

psutil provides cross-platform APIs with consistent interfaces. Some features may have platform-specific availability or behavior differences. Platform-specific features are clearly documented in the respective sections.

Supported platforms: Linux, Windows, macOS, FreeBSD, OpenBSD, NetBSD, AIX, Solaris