gpu-histop

gpu-histop is a high-resolution terminal GPU history monitor. It samples GPU metrics into timestamped ring histories and renders min/max bucketed Braille graphs, giving each terminal cell a 2x4 subpixel plot.

Each GPU panel also includes a compact process overview with process type (C, G, or MPS), PID, resolved user, GPU memory, command, and MIG instance IDs when NVML reports them.

Install

From Homebrew:

brew tap sdraeger/gpu-histop
brew install gpu-histop

From the GitHub repository:

cargo install --git https://github.com/sdraeger/gpu-histop

After publishing the package to crates.io:

cargo install gpu-histop

Prebuilt binaries are attached to tagged GitHub releases for Linux and macOS.

Backends

• auto: use the first available real metrics backend.
• nvml: require NVIDIA NVML.
• nvidia-smi: use the NVIDIA command line tool when direct NVML loading is not available.
• amdgpu: use Linux AMDGPU sysfs metrics.
• apple: use Apple Silicon GPU metrics from macOS system tools.

auto tries NVML first, then nvidia-smi, Linux AMDGPU sysfs, and Apple Silicon. On Apple Silicon, auto starts with the Apple backend so macOS does not report irrelevant NVIDIA/Linux backend errors. If none of the real backends is available, startup fails instead of showing generated demo data. The Apple backend first tries non-root ioreg performance counters and falls back to powermetrics, which usually requires administrator privileges on macOS. On Apple Silicon, GPU memory is unified memory rather than discrete VRAM; when available, gpu-histop reports the GPU-resident unified-memory counters in the VRAM field.

Apple Silicon power and clock metrics come from powermetrics, so they are only shown when the process has privileges to run that sampler. Recent Apple Silicon macOS releases generally expose thermal pressure rather than a stable GPU die temperature in degrees Celsius through built-in command-line tools, so temperature remains n/a unless Apple exposes a Celsius sensor through the sampled sources. Fan speed is naturally n/a on fanless devices.

Run

Terminal UI:

gpu-histop --backend auto --sample-ms 100 --window-seconds 60

From a source checkout:

cargo run --release -- --backend auto --sample-ms 100 --window-seconds 60

Native GUI:

cargo run --release --bin gpu-histop-gui -- --backend auto --sample-ms 100 --window-seconds 60

The GUI requires an available X11 or Wayland display. On a headless machine, use the TUI, run with X forwarding, or launch under a virtual display such as Xvfb.

Probe NVML process reporting without opening the TUI:

cargo run --example process_probe

The GUI shows raw sampled points over the selected history window, one high-density plot per metric, with a GPU selector and process table for the selected GPU.

Keys:

• q or Esc: quit
• Up / Down or j / k: select a GPU
• p or Enter: open the process popup for the selected GPU
• + / -: zoom the visible history window

Process popup keys:

• Up / Down, PageUp / PageDown, Home, End: scroll processes
• Tab / Shift+Tab: switch GPU
• Esc, p, or Enter: close the popup

Notes

NVML utilization counters are reported over the hardware sampling period exposed by the NVIDIA driver, which can be coarser than the poll interval on some GPUs. gpu-histop still keeps monotonic timestamps for every poll and preserves within-column min/max ranges so spikes remain visible after downsampling to the terminal.

Some enclosure-cooled NVIDIA data center GPUs do not expose a useful onboard fan reading through Linux/NVML. When such a device returns a known bogus 0%/0 RPM fan channel, gpu-histop reports fan speed as n/a instead of plotting a flat zero line.