Skip to main content

roctop

roctop is a lightweight terminal monitor for AMD ROCm GPUs. It gives you a live, keyboard-driven view of GPU health, memory pressure, utilization, history graphs, and the processes currently using your accelerators.

It is built for busy ROCm machines where you want the quick feel of top, but with GPU details that are easier to scan than raw rocm-smi output.

Demo

roctop demo

The demo uses synthetic data. Process names, users, PIDs, paths, and metrics are placeholders.

Highlights

  • Live Rich terminal UI for AMD GPUs.
  • Compact per-GPU table with model, architecture, GUID, temperature, fan, power, clocks, VRAM usage, and utilization.
  • Host and GPU history graphs for CPU, system memory, GPU utilization, and GPU memory pressure.
  • Process table with GPU index, PID, user, GPU memory, host CPU/memory, elapsed time, and wrapped command lines.
  • Interactive search, filtering, sorting, GPU focus, table zoom, process tree navigation, and process inspection.
  • Confirmation flow for SIGTERM/SIGKILL actions.
  • Scriptable --once and --json modes.

Requirements

  • Python 3.10 or newer.
  • ROCm command-line tools on PATH.
  • rocm-smi is required for GPU snapshots.
  • amd-smi is optional and used when available for richer GPU/process details.

roctop is designed for Linux ROCm systems. On machines without ROCm tools it will fail fast with a clear command error.

Install

pip install roctop

From source:

git clone https://github.com/nrhevu/roctop.git
cd roctop
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/roctop

Usage

Start the live monitor:

roctop

Common commands:

roctop --interval 0.5
roctop --once
roctop --json
roctop --version
python -m roctop --once

Options:

--interval SECONDS   refresh interval for the live view, minimum: 0.05, default: 1.0
--once               render one terminal snapshot and exit
--json               print one normalized JSON snapshot and exit
--version            print the package version

Live Controls

j/k or Up/Down       move process cursor
PgUp/PgDn            move process cursor by page
0-9                  focus a GPU, when that GPU index exists
s                    open sort menu
t                    toggle process tree
z                    zoom process table
g                    toggle GPU graphs
,/.                  pan graphs older/newer
r                    reset graphs to live
/                    search processes
n/N                  next/previous search match
f                    filter processes
i                    inspect selected process
Space                select or deselect process
x                    open kill confirmation
Esc                  close graphs/menus or clear active filters
?                    open or close help
q or Ctrl-C          quit

Tree mode:

p                    jump to parent process
h or Left            jump to previous sibling
l or Right           jump to next sibling

Menus and popups:

h/l or arrows        move sort/kill menu selection
Enter                apply selected sort or kill option
y                    send SIGTERM in kill confirmation
j/k or Up/Down       scroll help or process inspection
h/l or Left/Right    page help or process inspection
Esc or q             cancel menus

Data Sources

roctop combines several local data sources:

  • rocm-smi --json for core GPU state and ROCm driver information.
  • amd-smi static --json and amd-smi metric --json for extra model and metric details when available.
  • amd-smi process -G --json for GPU process memory when available.
  • /proc, ps, and container metadata for process command, user, runtime, CPU, host memory, ancestor, and container context.

Collection is intentionally tolerant. If optional process or detail commands are missing, slow, or malformed, the live monitor keeps rendering the best available snapshot.

Development

Create an editable install:

python3 -m venv --system-site-packages .venv
.venv/bin/python -m pip install -e .

Run tests:

.venv/bin/python -m unittest discover -s tests

Run local checks against the current machine:

.venv/bin/roctop --once
.venv/bin/roctop --json

Refresh the synthetic demo asset:

skills/roctop-demo-svg/scripts/generate_demo_svg.py

License

MIT. See LICENSE.

Metadata

Release files for roctop 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for roctop 1.0.1
File Size Uploaded Provenance Actions
roctop-1.0.1.tar.gz 93.6 kB With provenance Details for roctop-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for roctop 1.0.1
File Interpreter ABI Platform Actions
roctop-1.0.1-py3-none-any.whl Python 3 none any Details for roctop-1.0.1-py3-none-any.whl

Total release size: 149.3 kB

Release files / roctop-1.0.1.tar.gz

Download URL roctop-1.0.1.tar.gz
Size 93.6 kB
Tags Source
SHA-256 checksum
How to use checksums
3164e78759163c0728180764100613fec81081566fff402c64ce5d883b6274dd
BLAKE2b-256 checksum
How to use checksums
8cbcf21a7efea72181f620617b8e37ea7f648036963270b8d71b76ba92a87870
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / roctop-1.0.1-py3-none-any.whl

Download URL roctop-1.0.1-py3-none-any.whl
Size 55.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
40ba3a9cf2bf7620e322f359a71e8983afe3d6d8481956b85e9fb116cf3d213b
BLAKE2b-256 checksum
How to use checksums
48739deced44131dc169edbf79445b73ea0e23788722e9871b8c351d49213658
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for roctop 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for roctop-1.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page