amdtop

An nvitop-style interactive GPU monitor for AMD GPUs

English | 中文

---

English

Features

• Real-time monitoring of AMD GPU metrics (utilization, memory, temperature, power, clocks)
• Per-process GPU memory attribution via KFD sysfs interface
• Multi-GPU support with automatic filtering of virtual XCP partitions
• Interactive TUI with history graphs (120-second rolling window)
• No root required – works as a normal user in the render group
• Pure Python + sysfs – no external GPU libraries, no sudo, no ROCm Python bindings

Supported Metrics

✅ Device-level (per GPU):

• GPU utilization % (gpu_busy_percent)
• Memory bandwidth utilization % (mem_busy_percent)
• VRAM used/total (from mem_info_vram_*)
• Temperature (junction + memory, from hwmon)
• Power consumption + power cap
• GPU/memory clock frequencies
• Performance mode

✅ Per-process:

• VRAM usage per GPU (from /sys/class/kfd/kfd/proc/<pid>/vram_<gpu_id>)
• Process owner, PID, command line
• GPU assignment mapping

✅ Host metrics:

• CPU load average and utilization
• System memory usage

Installation

From the PPA (Ubuntu)

sudo add-apt-repository ppa:leeleno/amdtop
sudo apt update
sudo apt install amdtop

From source

git clone https://github.com/LeeLeno/amdtop.git
cd amdtop
pip install --user .

Or install directly without cloning:

pip install --user git+https://github.com/LeeLeno/amdtop.git

Manual installation

# Copy the script to your PATH
curl -o ~/.local/bin/amdtop https://raw.githubusercontent.com/LeeLeno/amdtop/main/amdtop.py
chmod +x ~/.local/bin/amdtop

Usage

# Interactive TUI (default)
amdtop

# Single snapshot (plain text)
amdtop --once

# JSON output for scripting
amdtop --json

# Slower refresh rate (2 seconds)
amdtop --interval 2.0

# ASCII mode (no Unicode box drawing)
amdtop --ascii

# Show help
amdtop --help

Keyboard shortcuts (interactive mode):

Key	Action
q, Q, ESC	quit
h, ?	toggle help overlay
x	toggle XGMI topology overlay
c, C	toggle compact device rows
0–9	focus a single GPU by index
a, A	clear focus, show all GPUs
s	cycle process sort key (GPU memory → CPU% → PID → elapsed → GPU index)
r, R	reverse sort order
u, U	toggle between all processes and your own only
↑, ↓	scroll the process table
Home	return process table to top
PgUp, PgDn	scroll the device table
+, =	double the refresh interval (max 60s)
-, _	halve the refresh interval (min 0.1s)

Requirements

• Linux kernel 6.8+ with amdgpu driver
• Python 3.8+ (standard library only, no pip dependencies for core features)
• AMD GPU with ROCm support (tested on MI300X, should work on MI200/MI100/Radeon)
• User must be in render and video groups

Known Limitations

• Fan speed: Not available on passively cooled accelerators (MI300X); shows memory temperature instead
• Per-process GPU utilization: KFD cu_occupancy is always 0 on some configurations; amdtop infers utilization when exactly one process holds VRAM on a card (marked with ~ prefix)
• PCIe bandwidth: Not yet implemented (requires parsing binary gpu_metrics structure)
• SR-IOV VFs: XGMI error counters and some advanced metrics are not exposed

Tested Platforms

• ✅ AMD Instinct MI300X (8× 192GB) on Ubuntu 24.04 + ROCm 7.0.2
• ✅ SR-IOV virtual functions in KVM

License

MIT License. See LICENSE for details.

Packaging

Debian packaging lives in debian/, and the scripts to build and publish it to a Launchpad PPA are in packaging/. See packaging/README.md for the full procedure.

Contributing

Issues and pull requests welcome! Please ensure:

• No external dependencies beyond Python standard library
• Maintain non-root compatibility
• Test on at least one AMD GPU platform

---

中文

功能特性

• 实时监控 AMD GPU 指标（利用率、显存、温度、功耗、频率）
• 进程级显存归属（通过 KFD sysfs 接口）
• 多卡支持，自动过滤虚拟 XCP 分区
• 交互式 TUI，带历史曲线（120 秒滚动窗口）
• 无需 root 权限 – 普通用户（render 组）即可运行
• 纯 Python + sysfs – 不依赖外部 GPU 库、无需 sudo、无需 ROCm Python 绑定

支持的指标

✅ 设备级（每个 GPU）：

• GPU 利用率 %（gpu_busy_percent）
• 显存带宽利用率 %（mem_busy_percent）
• VRAM 已用/总量（mem_info_vram_*）
• 温度（结温 + 显存温度，来自 hwmon）
• 功耗 + 功耗上限
• GPU/显存 时钟频率
• 性能模式

✅ 进程级：

• 每个 GPU 的 VRAM 占用（/sys/class/kfd/kfd/proc/<pid>/vram_<gpu_id>）
• 进程所有者、PID、命令行
• GPU 归属映射

✅ 主机指标：

• CPU 负载和利用率
• 系统内存占用

安装

从源码安装

git clone https://github.com/LeeLeno/amdtop.git
cd amdtop
pip install --user .

或直接安装：

pip install --user git+https://github.com/LeeLeno/amdtop.git

手动安装

# 下载脚本到 PATH
curl -o ~/.local/bin/amdtop https://raw.githubusercontent.com/LeeLeno/amdtop/main/amdtop.py
chmod +x ~/.local/bin/amdtop

使用

# 交互式 TUI（默认）
amdtop

# 单次快照（纯文本）
amdtop --once

# JSON 输出（脚本调用）
amdtop --json

# 降低刷新率（2 秒）
amdtop --interval 2.0

# ASCII 模式（无 Unicode 字符）
amdtop --ascii

# 显示帮助
amdtop --help

快捷键（交互模式）：

• q 或 Ctrl+C – 退出
• h – 切换帮助覆盖层
• p – 循环进程排序（GPU → VRAM → PID → 用户）
• x – 显示 XGMI 拓扑（多卡互联）

依赖要求

• Linux 内核 6.8+，带 amdgpu 驱动
• Python 3.8+（仅标准库，核心功能无 pip 依赖）
• AMD GPU，支持 ROCm（已在 MI300X 测试，应支持 MI200/MI100/Radeon）
• 用户需在 render 和 video 组

已知限制

• 风扇转速：被动散热加速卡（如 MI300X）无风扇，该列显示显存温度
• 进程级 GPU 利用率：部分配置下 KFD cu_occupancy 始终为 0；amdtop 在单进程独占卡时推断利用率（带 ~ 前缀标记）
• PCIe 带宽：尚未实现（需解析二进制 gpu_metrics 结构）
• SR-IOV VF：XGMI 错误计数器和部分高级指标不可见

测试平台

• ✅ AMD Instinct MI300X（8× 192GB），Ubuntu 24.04 + ROCm 7.0.2
• ✅ KVM 虚拟机内的 SR-IOV 虚拟功能

许可证

MIT 许可证。详见 LICENSE。

贡献

欢迎提交 Issue 和 PR！请确保：

• 仅依赖 Python 标准库
• 保持非 root 兼容性
• 至少在一个 AMD GPU 平台上测试