Python-Learning-Resources/psutil.md

# psutil 详细功能文档

`psutil`（Python System and Process Utilities）是一个跨平台的 Python 库，用于检索系统运行时的信息，如**CPU、内存、磁盘、网络、进程**等。它支持 Linux、Windows、macOS、FreeBSD 等主流操作系统，是系统监控、性能分析和运维自动化的重要工具。

---

## 一、安装与导入

### 1. 安装
```bash
pip install psutil
```

### 2. 导入
```python
import psutil
```

---

## 二、CPU 相关功能

### 1. CPU 逻辑/物理核心数
```python
psutil.cpu_count()          # 逻辑 CPU 数量
psutil.cpu_count(logical=False)  # 物理 CPU 数量
```

### 2. CPU 使用率
```python
psutil.cpu_percent(interval=1)      # 整体 CPU 使用率（阻塞 1 秒）
psutil.cpu_percent(interval=None)   # 非阻塞调用

psutil.cpu_times_percent(interval=1)
# 返回用户态、系统态、空闲等占比
```

### 3. 每个 CPU 核心的使用率
```python
psutil.cpu_percent(interval=1, percpu=True)
```

### 4. CPU 时间统计
```python
psutil.cpu_times()
# user / system / idle / iowait 等
```

---

## 三、内存相关功能

### 1. 虚拟内存（RAM）
```python
mem = psutil.virtual_memory()
print(mem.total, mem.available, mem.percent)
```

主要字段说明：

| 属性 | 含义 |
|----|----|
| total | 总内存 |
| available | 可用内存 |
| used | 已使用内存 |
| free | 完全空闲内存 |
| percent | 使用百分比 |

### 2. 交换内存（Swap）
```python
swap = psutil.swap_memory()
print(swap.total, swap.used, swap.free)
```

---

## 四、磁盘相关功能

### 1. 磁盘分区信息
```python
psutil.disk_partitions()
```

示例返回：
```text
sdiskpart(device='/dev/sda1', mountpoint='/', fstype='ext4')
```

### 2. 磁盘使用情况
```python
psutil.disk_usage('/')
```

返回字段：`total / used / free / percent`

### 3. 磁盘 I/O 统计
```python
psutil.disk_io_counters()
```

字段包括：
- `read_bytes`
- `write_bytes`
- `read_count`
- `write_count`

按磁盘：
```python
psutil.disk_io_counters(perdisk=True)
```

---

## 五、网络相关功能

### 1. 网络 I/O 统计
```python
psutil.net_io_counters()
```

字段：
- `bytes_sent`
- `bytes_recv`
- `packets_sent`
- `packets_recv`

按网卡：
```python
psutil.net_io_counters(pernic=True)
```

### 2. 网络连接
```python
psutil.net_connections(kind='inet')
```

常用 `kind`：
- `'inet'`：IPv4 + IPv6
- `'tcp'`
- `'udp'`

返回对象包含：
- `fd`, `family`, `type`, `laddr`, `raddr`, `status`, `pid`

### 3. 网络接口信息
```python
psutil.net_if_addrs()
psutil.net_if_stats()
```

---

## 六、进程管理（核心功能）

### 1. 获取进程 PID
```python
psutil.pids()
```

### 2. 创建 Process 对象
```python
p = psutil.Process(pid=1234)
```

### 3. 常用进程信息
```python
p.name()        # 进程名
p.exe()         # 可执行文件路径
p.cmdline()     # 启动命令
p.pid           # PID
p.ppid()        # 父 PID
p.status()      # 状态
p.create_time() # 创建时间
```

### 4. CPU / 内存使用
```python
p.cpu_percent(interval=0.1)
p.memory_info()     # RSS / VMS
p.memory_percent()
```

### 5. 线程与文件
```python
p.threads()
p.open_files()
```

### 6. 网络连接
```python
p.net_connections()
```

### 7. 进程控制
```python
p.suspend()
p.resume()
p.kill()
p.terminate()
```

---

## 七、系统信息与传感器

### 1. 系统基本信息
```python
psutil.boot_time()
psutil.users()
```

### 2. 温度传感器（Linux）
```python
psutil.sensors_temperatures()
```

### 3. 电池信息（笔记本）
```python
psutil.sensors_battery()
```

---

## 八、跨平台注意事项

| 功能 | Windows | Linux | macOS |
|----|----|----|----|
| 进程 CPU affinity | ❌ | ✅ | ❌ |
| sensors_temperature | ❌ | ✅ | ⚠️ |
| 完整 net_connections | ⚠️ | ✅ | ✅ |

> ⚠️ 表示部分支持或需要管理员权限

---

## 九、常见应用场景

- 系统资源实时监控
- 服务器性能分析
- 进程级资源审计
- 自动化运维脚本
- 安全/异常进程检测

---

## 十、总结

`psutil` 提供了**统一、简洁、跨平台**的系统信息访问接口，是 Python 中做系统监控和运维自动化的首选库之一。无论是查看 CPU、内存、磁盘、网络，还是精细到单个进程的资源占用，`psutil` 都能高效胜任。