nvitop

library1.7.0pypypi✓ verified 84d ago

nvitop is an interactive NVIDIA GPU device and process monitoring tool written in Python. It provides a colorful and informative interface that continuously updates the status of GPUs and processes, offering more details and interactivity than the default `nvidia-smi`. Beyond its CLI, it exposes a comprehensive Python API for custom monitoring and integrates with tools like Grafana via `nvitop-exporter`. The current version is 1.6.2, with a regular release cadence addressing new `nvidia-ml-py` versions, features, and bug fixes.

observability devops ai-ml

pip install nvitop

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · NVITOP

nvitop

observabilitypythonv1.7.0

Install

1.9s avg

Import

324ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.7.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

installs and imports cleanly · install 0.0s · import 0.340s · 20.6MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 1.9s · import 0.309s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Device

✓ from nvitop import Device

HostProcess

✓ from nvitop.process import HostProcess

take_snapshots

✓ from nvitop import take_snapshots

select_devices

✓ from nvitop import select_devices

This quickstart script demonstrates how to get an overview of your NVIDIA GPUs and list the processes currently utilizing them using nvitop's Python API. It fetches device details like temperature, utilization, and memory, then lists active GPU processes with their respective memory usage.

import os from nvitop import Device, take_snapshots # It's recommended to set CUDA_DEVICE_ORDER for consistent device indexing os.environ['CUDA_DEVICE_ORDER'] = 'PCI_BUS_ID' print("--- Device Overview ---") devices = Device.all() if not devices: print("No NVIDIA GPUs found or NVML not initialized.") else: for device in devices: print(f"Device {device.index}: {device.name()}") print(f" - Fan speed: {device.fan_speed() if device.fan_speed() is not None else 'N/A'}%") print(f" - Temperature: {device.temperature()}C") print(f" - GPU Utilization: {device.gpu_utilization()}% (SM), {device.memory_utilization()}% (Memory)") print(f" - Total Memory: {device.total_memory_human()}") print("\n--- Running GPU Processes ---") snapshots = take_snapshots() if not snapshots.gpu_processes: print("No GPU processes found.") else: for gpu_process in snapshots.gpu_processes: print(f"PID: {gpu_process.pid}, Name: {gpu_process.name()}, GPU: {gpu_process.device.index}, Mem: {gpu_process.gpu_memory_human()}")

nvitop --version

Debug

Known issues

breakingPython 3.7 support was officially dropped in nvitop v1.5.0. Users on Python 3.7 or older must upgrade their Python environment to at least 3.8 to use nvitop v1.5.0 or newer.

fix

Upgrade Python to version 3.8 or higher.

affects: >=1.5.0

deprecatedThe `nvitop.callbacks` module was officially deprecated in v1.5.0 and is now unmaintained. Users relying on these callbacks should migrate to alternative integration methods or the core API.

fix

Refactor code to use nvitop's core API directly or explore other integration patterns for machine learning frameworks.

affects: >=1.5.0

gotchaThe recommended way to install `nvidia-ml-py` with `nvitop` changed in v1.5.3. Instead of using per-version install extras like `nvitop[nvml-11.450.129]`, users should now use `nvitop[cudaXX]` where `XX` is the major CUDA version (e.g., `nvitop[cuda11]`).

fix

Update installation commands to use `pip install 'nvitop[cudaXX]'` syntax for specific NVIDIA driver compatibility.

affects: >=1.5.3

gotchanvitop relies on the NVIDIA Management Library (NVML), which is part of the NVIDIA display driver or CUDA Toolkit. Without a properly installed and functional NVIDIA driver, nvitop will not be able to detect GPUs or collect metrics.

fix

Ensure that a compatible NVIDIA display driver (or CUDA Toolkit) is installed and that the NVML library is accessible on your system.

affects: All versions

gotchaOn Windows, the TUI (Terminal User Interface) features of nvitop require the `windows-curses` package. Inconsistent behavior may occur on different terminal emulators, such as missing mouse support, even with the package installed.

fix

Install `windows-curses` via `pip install windows-curses`. For best TUI experience on Windows, consider using a compatible terminal emulator.

affects: All versions on Windows

Errors

Common errors & fixes

nvitop: command not found

The directory where Python installs console scripts (e.g., `~/.local/bin` on Linux or a `Scripts` directory in your Python installation on Windows) is not included in your system's PATH environment variable, or nvitop was installed in a virtual environment not currently activated.

fix

Run nvitop using `python -m nvitop` instead of just `nvitop`. Alternatively, add the Python console script path to your system's PATH environment variable.

ModuleNotFoundError: No module named '_curses'

This error occurs specifically on Windows because the `curses` library, which `nvitop` uses for its interactive terminal interface, is a Unix-specific module and is not built-in on Windows.

fix

Install the `windows-curses` package: `pip install windows-curses`.

AttributeError: module 'pynvml' has no attribute '_nvmlGetFunctionPointer'

`nvitop` relies on `nvidia-ml-py` (which provides the `pynvml` module) to interface with the NVIDIA Management Library (NVML); this error, or related issues like incorrect GPU process display or 'No Such Process', often indicates an incompatibility between the installed `nvidia-ml-py` version and your NVIDIA GPU driver, or conflicts with other packages pinning `nvidia-ml-py` to a different version.

fix

Ensure `nvidia-ml-py` is compatible with your NVIDIA driver version. Check the `nvidia-ml-py` release history for compatible versions and install a specific one (e.g., `pip install nvidia-ml-py==XX.YYY.ZZ nvitop`) or install `nvitop` in a clean virtual environment to avoid conflicts.

Upgrade

Version history

1.7.0latest on PyPI · released May 16, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.8 or newer for core functionality.

nvidia-ml-pyrequiredCore dependency for interacting with NVIDIA GPUs via NVML. Specific versions are handled by 'nvitop[cudaXX]' extras.

windows-cursesoptionalRequired for TUI functionality on Windows operating systems.

Agent activity

56 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/XuehaiPan/nvitop ↗

packagehttps://pypi.org/project/nvitop/ ↗

docshttps://nvitop.readthedocs.io ↗