{"slug": "nvitop-a-better-top-for-nvidia-gpus", "title": "Nvitop: A better top for Nvidia GPUs", "summary": "Nvitop is an open-source interactive NVIDIA GPU process viewer and monitoring tool that queries device status directly through NVML Python bindings rather than parsing nvidia-smi output. The package ships a CUDA device selection tool called nvisel for deep learning researchers and provides APIs for developers to build their own monitoring tools, running on both Linux and Windows with Python 3.8+ and dependencies including nvidia-ml-py, psutil, and curses. Nvitop adds monitor mode with bar charts, history graphs, process sorting, filtering, tree-view, environment variable screens, and keystroke signal sending over nvidia-smi.", "body_md": "An interactive NVIDIA-GPU process viewer and beyond, the one-stop solution for GPU process management. The full API references host at [https://nvitop.readthedocs.io](https://nvitop.readthedocs.io).\n\n Monitor mode of `nvitop`.\n \n\n (TERM: GNOME Terminal / OS: Ubuntu 16.04 LTS (over SSH) / Locale: `en_US.UTF-8`)\n\n A Grafana dashboard built on top of `nvitop-exporter`.\n\n`nvitop` is an interactive NVIDIA device and process monitoring tool. It has a colorful and informative interface that continuously updates the status of the devices and processes. As a resource monitor, it includes many features and options, such as tree-view, environment variable viewing, process filtering, process metrics monitoring, etc. Beyond that, the package also ships a [CUDA device selection tool `nvisel`](#cuda-visible-devices-selection-tool) for deep learning researchers. It also provides handy APIs that allow developers to write their own monitoring tools. Please refer to section [More than a Monitor](#more-than-a-monitor) and the full API references at [https://nvitop.readthedocs.io](https://nvitop.readthedocs.io) for more information.\n\n Process filtering and a more colorful interface.\n\n- **Informative and fancy output** : show more information than`nvidia-smi` with colorized fancy box drawing.\n- **Monitor mode** : can run as a resource monitor, rather than print the results only once.\n - bar charts and history graphs\n - process sorting\n - process filtering\n - send signals to processes with a keystroke\n - tree-view screen for GPU processes and their parent processes\n - environment variable screen\n - help screen\n - mouse support\n- **Interactive** : responsive for user input (from keyboard and/or mouse) in monitor mode. (vs.[gpustat](https://github.com/wookayin/gpustat) &[py3nvml](https://github.com/fbcotter/py3nvml) )\n- **Efficient** :\n - query device status using [*NVML Python bindings*](https://pypi.org/project/nvidia-ml-py) directly, instead of parsing the output of`nvidia-smi` . (vs.[nvidia-htop](https://github.com/peci1/nvidia-htop) )\n - support sparse query and cache results with `TTLCache` from[cachetools](https://github.com/tkem/cachetools) . (vs.[gpustat](https://github.com/wookayin/gpustat) )\n - display information using the `curses` library rather than`print` with ANSI escape codes. (vs.[py3nvml](https://github.com/fbcotter/py3nvml) )\n - asynchronously gather information using multi-threading and correspond to user input much faster. (vs. [nvtop](https://github.com/Syllo/nvtop) )\n- query device status using \n- **Portable** : work on both Linux and Windows.\n - get host process information using the cross-platform library [psutil](https://github.com/giampaolo/psutil) instead of calling`ps -p ` in a subprocess. (vs.[nvidia-htop](https://github.com/peci1/nvidia-htop) &[py3nvml](https://github.com/fbcotter/py3nvml) )\n - written in pure Python, easy to install with `pip` . (vs.[nvtop](https://github.com/Syllo/nvtop) )\n- get host process information using the cross-platform library \n- **Integrable** : easy to integrate into other applications, more than monitoring. (vs.[nvidia-htop](https://github.com/peci1/nvidia-htop) &[nvtop](https://github.com/Syllo/nvtop) )\n\n`nvitop` supports Windows!\n \n\n (SHELL: PowerShell / TERM: Windows Terminal / OS: Windows 10 / Locale: `en-US`)\n\n- Python 3.8+\n- NVIDIA Management Library (NVML)\n- nvidia-ml-py\n- psutil\n- curses[*](#curses) (with`libncursesw` )\n\n**NOTE:** The [NVIDIA Management Library (*NVML*)](https://developer.nvidia.com/nvidia-management-library-nvml) is a C-based programmatic interface for monitoring and managing various states. The runtime version of the NVML library ships with the NVIDIA display driver (available at [Download Drivers | NVIDIA](https://www.nvidia.com/Download/index.aspx)), or can be downloaded as part of the NVIDIA CUDA Toolkit (available at [CUDA Toolkit | NVIDIA Developer](https://developer.nvidia.com/cuda-downloads)). The lists of OS platforms and NVIDIA-GPUs supported by the NVML library can be found in the [NVML API Reference](https://docs.nvidia.com/deploy/nvml-api/nvml-api-reference.html).\n\nThis repository contains a Bash script to install/upgrade the NVIDIA drivers for Ubuntu Linux. For example:\n\n```\ngit clone --depth=1 https://github.com/XuehaiPan/nvitop.git && cd nvitop\n\n# Change to tty3 console (required for desktop users with GUI (tty2))\n# Optional for SSH users\nsudo chvt 3 # or use keyboard shortcut: Ctrl-LeftAlt-F3\n\nbash install-nvidia-driver.sh --package=nvidia-driver-595 # install the R595 driver from ppa:graphics-drivers\nbash install-nvidia-driver.sh --latest # install the latest driver from ppa:graphics-drivers\nbash install-nvidia-driver.sh --latest --open # install the latest open-kernel-module driver\n```\n\n NVIDIA driver installer for Ubuntu Linux.\n\nRun `bash install-nvidia-driver.sh --help` for more information.\n\n[*] The `curses` library is a built-in module of Python on Unix-like systems, and it is supported by a third-party package called `windows-curses` on Windows using PDCurses. Inconsistent behavior of `nvitop` may occur on different terminal emulators on Windows, such as missing mouse support.\n\n**It is highly recommended to install `nvitop` in an isolated virtual environment.** Simple installation and run via [`uvx`](https://docs.astral.sh/uv/guides/tools) (a.k.a. `uv tool run`) or [` pipx`](https://pypa.github.io/pipx):\n\n```\nuvx nvitop\n# or\npipx run nvitop\n```\n\nYou can also set this command as an alias in your shell startup file, e.g.:\n\n```\n# For Bash\necho 'alias nvitop=\"uvx nvitop\"' >> ~/.bashrc\n\n# For Zsh\necho 'alias nvitop=\"uvx nvitop\"' >> ~/.zshrc\n\n# For Fish\nmkdir -p ~/.config/fish\necho 'alias nvitop=\"uvx nvitop\"' >> ~/.config/fish/config.fish\n\n# For PowerShell\nNew-Item -Path (Split-Path -Parent -Path $PROFILE.CurrentUserAllHosts) -ItemType Directory -Force\n'Function nvitop { uvx nvitop @Args }' >> $PROFILE.CurrentUserAllHosts\n```\n\nor\n\n```\n# For Bash\necho 'alias nvitop=\"pipx run nvitop\"' >> ~/.bashrc\n\n# For Zsh\necho 'alias nvitop=\"pipx run nvitop\"' >> ~/.zshrc\n\n# For Fish\nmkdir -p ~/.config/fish\necho 'alias nvitop=\"pipx run nvitop\"' >> ~/.config/fish/config.fish\n\n# For PowerShell\nNew-Item -Path (Split-Path -Parent -Path $PROFILE.CurrentUserAllHosts) -ItemType Directory -Force\n'Function nvitop { pipx run nvitop @Args }' >> $PROFILE.CurrentUserAllHosts\npip3 install --upgrade nvitop\nconda install -c conda-forge nvitop\n```\n\nInstall the latest version from GitHub ([):](https://camo.githubusercontent.com/673a0879f7c175fb049fd033a13194b80884f597d0387e8d08188d76bf21d2f7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6d6d6974732d73696e63652f58756568616950616e2f6e7669746f702f76312e372e31)\n\n```\npip3 install --upgrade pip setuptools\npip3 install git+https://github.com/XuehaiPan/nvitop.git\n```\n\nOr, clone this repo and install manually:\n\n```\ngit clone --depth=1 https://github.com/XuehaiPan/nvitop.git && cd nvitop\npip3 install .\n```\n\n**NOTE:** If you encounter the *\"nvitop: command not found\"* error after installation, please check whether you have added the Python console script path (e.g., `\"${HOME}/.local/bin\"`) to your `PATH` environment variable. Alternatively, you can use `python3 -m nvitop`.\n\nQuery the device and process status. The output is similar to `nvidia-smi`, but has been enriched and colorized.\n\n``` bash\n# Query the status of all devices\n$ nvitop -1 # or use `python3 -m nvitop -1`\n\n# Specify query devices (by integer indices)\n$ nvitop -1 -o 0 1 # only show and \n\n# Only show devices in `CUDA_VISIBLE_DEVICES` (by integer indices or UUID strings)\n$ nvitop -1 -ov\n\n# Only show GPU processes with the compute context (type: 'C' or 'C+G')\n$ nvitop -1 -c\n```\n\nWhen the `-1` switch is on, the result will be displayed **ONLY ONCE** (same as the default behavior of `nvidia-smi`). This is much faster and has lower resource usage. See [Command Line Options](#command-line-options-and-environment-variables) for more command options.\n\nThere is also a CLI tool called `nvisel` that ships with the `nvitop` PyPI package. See [CUDA Visible Devices Selection Tool](#cuda-visible-devices-selection-tool) for more information.\n\nRun as a resource monitor:\n\n```\n# Monitor mode (when the display mode is omitted, `NVITOP_MONITOR_MODE` will be used)\n$ nvitop # or use `python3 -m nvitop`\n\n# Automatically configure the display mode according to the terminal size\n$ nvitop -m auto # shortcut: `a` key\n\n# Arbitrarily display as `full` mode\n$ nvitop -m full # shortcut: `f` key\n\n# Arbitrarily display as `compact` mode\n$ nvitop -m compact # shortcut: `c` key\n\n# Specify query devices (by integer indices)\n$ nvitop -o 0 1 # only show and \n\n# Only show devices in `CUDA_VISIBLE_DEVICES` (by integer indices or UUID strings)\n$ nvitop -ov\n\n# Only show GPU processes with the compute context (type: 'C' or 'C+G')\n$ nvitop -c\n\n# Use ASCII characters only\n$ nvitop -U # useful for terminals without Unicode support\n\n# For light terminals\n$ nvitop --light\n\n# For spectrum-like bar charts (requires the terminal supports 256-color)\n$ nvitop --colorful\n```\n\nYou can configure the default monitor mode with the `NVITOP_MONITOR_MODE` environment variable (default `auto` if not set). See [Command Line Options and Environment Variables](#command-line-options-and-environment-variables) for more command options.\n\nIn monitor mode, you can use `Ctrl-c` / `T` / `K` keys to interrupt / terminate / kill a process. And it's recommended to *terminate* or *kill* a process in the **tree-view screen** (shortcut: `t`). For normal users, `nvitop` will shallow other users' processes (in low-intensity colors). For **system administrators**, you can use `sudo nvitop` to terminate other users' processes.\n\nTo run `nvitop` as a viewer only and disable all process-mutating shortcuts, pass `--readonly` (or set `NVITOP_MONITOR_MODE=\"readonly\"`). The signal keys above become no-ops, the on-screen \"Press ^C(INT)/T(TERM)/K(KILL) to send signals\" hint is hidden, and the corresponding rows in the help screen are dimmed. Use this when sharing a session over SSH, demoing on a multi-tenant box, or wrapping `nvitop` in a non-admin alias.\n\nAlso, to enter the process metrics screen, select a process and then press the `Enter` / `Return` key . `nvitop` dynamically displays the process metrics with live graphs.\n\n Watch metrics for a specific process (shortcut: `Enter` / `Return`).\n\nPress `h` for help or `q` to return to the terminal. See [Keybindings for Monitor Mode](#keybindings-for-monitor-mode) for more shortcuts.\n\n`nvitop` comes with a help screen (shortcut: `h`).\n\nBuild and run the Docker image with [nvidia-container-toolkit](https://github.com/NVIDIA/nvidia-container-toolkit):\n\n```\ndocker run -it --rm --runtime=nvidia --gpus=all --pid=host ghcr.io/xuehaipan/nvitop:latest\n```\n\n**NOTE:** Don't forget to add the `--pid=host` option when running the container.\n\nIf you only need to set up the Grafana dashboard, you can start a dashboard at [`http://localhost:3000`](http://localhost:3000) with the following command:\n\n```\ndocker compose --project-directory=nvitop-exporter/grafana up --build --detach\n```\n\nSee [`nvitop-exporter`](https://github.com/XuehaiPan/nvitop/blob/main/nvitop-exporter/README.md) for more details.\n\nRun `nvitop` directly on the SSH session instead of a login shell:\n\n```\nssh user@host -t nvitop # installed by `sudo pip3 install ...`\nssh user@host -t '~/.local/bin/nvitop' # installed by `pip3 install --user ...`\n```\n\n**NOTE:** Users need to add the `-t` option to allocate a pseudo-terminal over the SSH session for monitor mode.\n\nType `nvitop --help` for more command options:\n\n```\nusage: nvitop [--help] [--version] [--once | --monitor [{auto,full,compact}]]\n [--interval SEC] [--no-unicode] [--readonly] [--colorful]\n [--force-color] [--light] [--gpu-util-thresh th1 th2]\n [--mem-util-thresh th1 th2] [--only INDEX [INDEX ...]]\n [--only-visible] [--compute] [--only-compute] [--graphics]\n [--only-graphics] [--user [USERNAME ...]] [--pid PID [PID ...]]\n\nAn interactive NVIDIA-GPU process viewer.\n\noptions:\n --help, -h Show this help message and exit.\n --version, -V Show nvitop's version number and exit.\n --once, -1 Report query data only once.\n --monitor, -m [{auto,full,compact}]\n Run as a resource monitor. Continuously report query data and handle user inputs.\n If the argument is omitted, the value from `NVITOP_MONITOR_MODE` will be used.\n (default fallback mode: auto)\n --interval SEC Process status update interval in seconds. (default: 2)\n --no-unicode, --ascii, -U\n Use ASCII characters only, which is useful for terminals without Unicode support.\n --readonly Disable all system and process changing features (e.g., terminating processes).\n Set variable `NVITOP_MONITOR_MODE=\"readonly\"` for convenience.\n\ncoloring:\n --colorful Use gradient colors to get spectrum-like bar charts.\n Set variable `NVITOP_MONITOR_MODE=\"colorful\"` for convenience.\n This option is only available when the terminal supports 256 colors.\n You may need to set environment variable `TERM=\"xterm-256color\"`. Note that the\n terminal multiplexer, such as `tmux`, may override the `TERM` variable.\n --force-color Force colorize even when `stdout` is not a TTY terminal.\n --light Tweak visual results for light theme terminals in monitor mode.\n Set variable `NVITOP_MONITOR_MODE=\"light\"` on light terminals for convenience.\n --gpu-util-thresh th1 th2\n Thresholds of GPU utilization to determine the load intensity.\n Coloring rules: light < th1 % <= moderate < th2 % <= heavy.\n ( 1 <= th1 < th2 <= 99, defaults: 10 75 )\n --mem-util-thresh th1 th2\n Thresholds of GPU memory percent to determine the load intensity.\n Coloring rules: light < th1 % <= moderate < th2 % <= heavy.\n ( 1 <= th1 < th2 <= 99, defaults: 10 80 )\n\ndevice filtering:\n --only, -o INDEX [INDEX ...]\n Only show the specified devices, suppress option `--only-visible`.\n --only-visible, -ov Only show devices in the `CUDA_VISIBLE_DEVICES` environment variable.\n\nprocess filtering:\n --compute, -c Only show GPU processes with the compute context. (type: 'C' or 'C+G')\n --only-compute, -C Only show GPU processes exactly with the compute context. (type: 'C' only)\n --graphics, -g Only show GPU processes with the graphics context. (type: 'G' or 'C+G')\n --only-graphics, -G Only show GPU processes exactly with the graphics context. (type: 'G' only)\n --user, -u [USERNAME ...]\n Only show processes of the given users (or `$USER` for no argument).\n --pid, -p PID [PID ...]\n Only show processes of the given PIDs.\n```\n\n`nvitop` can accept the following environment variables for monitor mode:\n\n| Name | Description | Valid Values | Default Value | \n|---|---|---|---|\n| `NVITOP_MONITOR_MODE` | The default display mode (a comma-separated string) | `auto` /`full` /`compact`` plain` /`colorful`` dark` /`light`` readonly` (disables process-mutating shortcuts) | `auto,plain,dark` | \n| `NVITOP_GPU_UTILIZATION_THRESHOLDS` | Thresholds of GPU utilization | `10,75` ,`1,99` , ... | `10,75` | \n| `NVITOP_MEMORY_UTILIZATION_THRESHOLDS` | Thresholds of GPU memory percent | `10,80` ,`1,99` , ... | `10,80` | \n| `LOGLEVEL` | Log level for log messages | `DEBUG` ,`INFO` ,`WARNING` , ... | `WARNING` | \n\nFor example:\n\n```\n# Replace the following export statements if you are not using Bash / Zsh\nexport NVITOP_MONITOR_MODE=\"full,light\"\n\n# Full monitor mode with light terminal tweaks\nnvitop\n```\n\nFor convenience, you can add these environment variables to your shell startup file, e.g.:\n\n```\n# For Bash\necho 'export NVITOP_MONITOR_MODE=\"full\"' >> ~/.bashrc\n\n# For Zsh\necho 'export NVITOP_MONITOR_MODE=\"full\"' >> ~/.zshrc\n\n# For Fish\necho 'set -gx NVITOP_MONITOR_MODE \"full\"' >> ~/.config/fish/config.fish\n\n# For PowerShell\n'$Env:NVITOP_MONITOR_MODE = \"full\"' >> $PROFILE.CurrentUserAllHosts\n```\n\n| Key | Binding | \n|---|---|\n| `q` | Quit and return to the terminal. | \n| `h` /`?` | Go to the help screen. | \n| `a` /`f` /`c` | Change the display mode to *auto* /*full* /*compact* . | \n| `r` /`` /`` | Force refresh the window. | \n| `` /```` /```` /```` | Select and highlight a process. | \n| `` /```` /```` | Scroll the host information of processes. | \n| `` | Select the first process. | \n| `` | Select the last process. | \n| ```^` | Scroll left to the beginning of the process entry (i.e. beginning of line). | \n| ```$` | Scroll right to the end of the process entry (i.e. end of line). | \n| `` /```` /```[` /`]` | scroll entire screen (for large amounts of processes). | \n| `` | Tag/untag current process. | \n| `` | Clear process selection. | \n| ``` I` | Send `signal.SIGINT` to the selected process (interrupt).*(disabled under `--readonly`)* | \n| `T` | Send `signal.SIGTERM` to the selected process (terminate).*(disabled under `--readonly`)* | \n| `K` | Send `signal.SIGKILL` to the selected process (kill).*(disabled under `--readonly`)* | \n| `e` | Show process environment. | \n| `t` | Toggle tree-view screen. | \n| `` | Show process metrics. | \n| `,` /`.` | Select the sort column. | \n| `/` | Reverse the sort order. | \n| `on` (`oN` ) | Sort processes in the natural order, i.e., in ascending (descending) order of `GPU` . | \n| `ou` (`oU` ) | Sort processes by `USER` in ascending (descending) order. | \n| `op` (`oP` ) | Sort processes by `PID` in descending (ascending) order. | \n| `og` (`oG` ) | Sort processes by `GPU-MEM` in descending (ascending) order. | \n| `os` (`oS` ) | Sort processes by `%SM` in descending (ascending) order. | \n| `oc` (`oC` ) | Sort processes by `%CPU` in descending (ascending) order. | \n| `om` (`oM` ) | Sort processes by `%MEM` in descending (ascending) order. | \n| `ot` (`oT` ) | Sort processes by `TIME` in descending (ascending) order. | \n\n**HINT:** It's recommended to terminate or kill a process in the tree-view screen (shortcut: `t`).\n\nAutomatically select `CUDA_VISIBLE_DEVICES` from the given criteria. Example usage of the CLI tool:\n\n``` bash\n# All devices but sorted\n$ nvisel # or use `python3 -m nvitop.select`\n6,5,4,3,2,1,0,7,8\n\n# A simple example to select 4 devices\n$ nvisel -n 4 # or use `python3 -m nvitop.select -n 4`\n6,5,4,3\n\n# Select available devices that satisfy the given constraints\n$ nvisel --min-count 2 --max-count 3 --min-free-memory 5GiB --max-gpu-utilization 60\n6,5,4\n\n# Set `CUDA_VISIBLE_DEVICES` environment variable using `nvisel`\n$ export CUDA_DEVICE_ORDER=\"PCI_BUS_ID\" CUDA_VISIBLE_DEVICES=\"$(nvisel -c 1 -f 10GiB)\"\nCUDA_VISIBLE_DEVICES=\"6,5,4,3,2,1,0\"\n\n# Use UUID strings in `CUDA_VISIBLE_DEVICES` environment variable\n$ export CUDA_VISIBLE_DEVICES=\"$(nvisel -O uuid -c 2 -f 5000M)\"\nCUDA_VISIBLE_DEVICES=\"GPU-849d5a8d-610e-eeea-1fd4-81ff44a23794,GPU-18ef14e9-dec6-1d7e-1284-3010c6ce98b1,GPU-96de99c9-d68f-84c8-424c-7c75e59cc0a0,GPU-2428d171-8684-5b64-830c-435cd972ec4a,GPU-6d2a57c9-7783-44bb-9f53-13f36282830a,GPU-f8e5a624-2c7e-417c-e647-b764d26d4733,GPU-f9ca790e-683e-3d56-00ba-8f654e977e02\"\n\n# Pipe output to other shell utilities\n$ nvisel --newline -O uuid -C 6 -f 8GiB\nGPU-849d5a8d-610e-eeea-1fd4-81ff44a23794\nGPU-18ef14e9-dec6-1d7e-1284-3010c6ce98b1\nGPU-96de99c9-d68f-84c8-424c-7c75e59cc0a0\nGPU-2428d171-8684-5b64-830c-435cd972ec4a\nGPU-6d2a57c9-7783-44bb-9f53-13f36282830a\nGPU-f8e5a624-2c7e-417c-e647-b764d26d4733\n$ nvisel -0 -O uuid -c 2 -f 4GiB | xargs -0 -I {} nvidia-smi --id={} --query-gpu=index,memory.free --format=csv\nCUDA_VISIBLE_DEVICES=\"GPU-849d5a8d-610e-eeea-1fd4-81ff44a23794,GPU-18ef14e9-dec6-1d7e-1284-3010c6ce98b1,GPU-96de99c9-d68f-84c8-424c-7c75e59cc0a0,GPU-2428d171-8684-5b64-830c-435cd972ec4a,GPU-6d2a57c9-7783-44bb-9f53-13f36282830a,GPU-f8e5a624-2c7e-417c-e647-b764d26d4733,GPU-f9ca790e-683e-3d56-00ba-8f654e977e02\"\nindex, memory.free [MiB]\n6, 11018 MiB\nindex, memory.free [MiB]\n5, 11018 MiB\nindex, memory.free [MiB]\n4, 11018 MiB\nindex, memory.free [MiB]\n3, 11018 MiB\nindex, memory.free [MiB]\n2, 11018 MiB\nindex, memory.free [MiB]\n1, 11018 MiB\nindex, memory.free [MiB]\n0, 11018 MiB\n\n# Normalize the `CUDA_VISIBLE_DEVICES` environment variable (e.g. convert UUIDs to indices or get full UUIDs for an abbreviated form)\n$ nvisel -i \"GPU-18ef14e9,GPU-849d5a8d\" -S\n5,6\n$ nvisel -i \"GPU-18ef14e9,GPU-849d5a8d\" -S -O uuid --newline\nGPU-18ef14e9-dec6-1d7e-1284-3010c6ce98b1\nGPU-849d5a8d-610e-eeea-1fd4-81ff44a23794\n```\n\nYou can also integrate `nvisel` into your training script like this:\n\n``` python\n# Put this at the top of the Python script\nimport os\nfrom nvitop import select_devices\n\nos.environ['CUDA_VISIBLE_DEVICES'] = ','.join(\n select_devices(format='uuid', min_count=4, min_free_memory='8GiB')\n)\n```\n\nType `nvisel --help` for more command options:\n\n```\nusage: nvisel [--help] [--version]\n [--inherit [CUDA_VISIBLE_DEVICES]] [--account-as-free [USERNAME ...]]\n [--min-count N] [--max-count N] [--count N]\n [--min-free-memory SIZE] [--min-total-memory SIZE]\n [--max-gpu-utilization RATE] [--max-memory-utilization RATE]\n [--tolerance TOL]\n [--format FORMAT] [--sep SEP | --newline | --null] [--no-sort]\n\nCUDA visible devices selection tool.\n\noptions:\n --help, -h Show this help message and exit.\n --version, -V Show nvisel's version number and exit.\n\nconstraints:\n --inherit [CUDA_VISIBLE_DEVICES], -i [CUDA_VISIBLE_DEVICES]\n Inherit the given `CUDA_VISIBLE_DEVICES`. If the argument is omitted, use the\n value from the environment. This means selecting a subset of the currently\n CUDA-visible devices.\n --account-as-free [USERNAME ...]\n Account the used GPU memory of the given users as free memory.\n If this option is specified but without argument, `$USER` will be used.\n --min-count N, -c N Minimum number of devices to select. (default: 0)\n The tool will fail (exit non-zero) if the requested resource is not available.\n --max-count N, -C N Maximum number of devices to select. (default: all devices)\n --count N, -n N Overriding both `--min-count N` and `--max-count N`.\n --min-free-memory SIZE, -f SIZE\n Minimum free memory of devices to select. (example value: 4GiB)\n If this constraint is given, check against all devices.\n --min-total-memory SIZE, -t SIZE\n Minimum total memory of devices to select. (example value: 10GiB)\n If this constraint is given, check against all devices.\n --max-gpu-utilization RATE, -G RATE\n Maximum GPU utilization rate of devices to select. (example value: 30)\n If this constraint is given, check against all devices.\n --max-memory-utilization RATE, -M RATE\n Maximum memory bandwidth utilization rate of devices to select. (example value: 50)\n If this constraint is given, check against all devices.\n --tolerance TOL, --tol TOL\n The constraints tolerance (in percentage). (default: 0, i.e., strict)\n This option can loose the constraints if the requested resource is not available.\n For example, set `--tolerance=20` will accept a device with only 4GiB of free\n memory when set `--min-free-memory=5GiB`.\n\nformatting:\n --format FORMAT, -O FORMAT\n The output format of the selected device identifiers. (default: index)\n If any MIG device found, the output format will be fallback to `uuid`.\n --sep SEP, --separator SEP, -s SEP\n Separator for the output. (default: ',')\n --newline Use newline character as separator for the output, equivalent to `--sep=$'\\n'`.\n --null, -0 Use null character ('\\x00') as separator for the output. This option corresponds\n to the `-0` option of `xargs`.\n --no-sort, -S Do not sort the device by memory usage and GPU utilization.\n```\n\n`nvitop` can be easily integrated into other applications. You can use `nvitop` to make your own monitoring tools. The full API references host at [https://nvitop.readthedocs.io](https://nvitop.readthedocs.io). Runnable reference scripts live in [`examples/`](https://github.com/XuehaiPan/nvitop/blob/main/examples).\n\n A browser dashboard example built on top of `nvitop.collect_in_background`.\n\nA minimal script to monitor the GPU devices based on APIs from `nvitop`:\n\n``` python\nfrom nvitop import Device\n\ndevices = Device.all() # or `Device.cuda.all()` to use CUDA ordinal instead\nfor device in devices:\n processes = device.processes() # type: Dict[int, GpuProcess]\n sorted_pids = sorted(processes.keys())\n\n print(device)\n print(f' - Fan speed: {device.fan_speed()}%')\n print(f' - Temperature: {device.temperature()}C')\n print(f' - GPU utilization: {device.gpu_utilization()}%')\n print(f' - Total memory: {device.memory_total_human()}')\n print(f' - Used memory: {device.memory_used_human()}')\n print(f' - Free memory: {device.memory_free_human()}')\n print(f' - Processes ({len(processes)}): {sorted_pids}')\n for pid in sorted_pids:\n print(f' - {processes[pid]}')\n print('-' * 120)\n```\n\nAnother more advanced approach with coloring:\n\n``` python\nimport time\n\nfrom nvitop import Device, GpuProcess, NA, colored\n\nprint(colored(time.strftime('%a %b %d %H:%M:%S %Y'), color='red', attrs=('bold',)))\n\ndevices = Device.cuda.all() # or `Device.all()` to use NVML ordinal instead\nseparator = False\nfor device in devices:\n processes = device.processes() # type: Dict[int, GpuProcess]\n\n print(colored(str(device), color='green', attrs=('bold',)))\n print(colored(' - Fan speed: ', color='blue', attrs=('bold',)) + f'{device.fan_speed()}%')\n print(colored(' - Temperature: ', color='blue', attrs=('bold',)) + f'{device.temperature()}C')\n print(colored(' - GPU utilization: ', color='blue', attrs=('bold',)) + f'{device.gpu_utilization()}%')\n print(colored(' - Total memory: ', color='blue', attrs=('bold',)) + f'{device.memory_total_human()}')\n print(colored(' - Used memory: ', color='blue', attrs=('bold',)) + f'{device.memory_used_human()}')\n print(colored(' - Free memory: ', color='blue', attrs=('bold',)) + f'{device.memory_free_human()}')\n if len(processes) > 0:\n processes = GpuProcess.take_snapshots(processes.values(), failsafe=True)\n processes.sort(key=lambda process: (process.username, process.pid))\n\n print(colored(f' - Processes ({len(processes)}):', color='blue', attrs=('bold',)))\n fmt = ' {pid:<5} {username:<8} {cpu:>5} {host_memory:>8} {time:>8} {gpu_memory:>8} {sm:>3} {command:<}'.format\n print(colored(fmt(pid='PID', username='USERNAME',\n cpu='CPU%', host_memory='HOST-MEM', time='TIME',\n gpu_memory='GPU-MEM', sm='SM%',\n command='COMMAND'),\n attrs=('bold',)))\n for snapshot in processes:\n print(fmt(pid=snapshot.pid,\n username=snapshot.username[:7] + ('+' if len(snapshot.username) > 8 else snapshot.username[7:8]),\n cpu=snapshot.cpu_percent, host_memory=snapshot.host_memory_human,\n time=snapshot.running_time_human,\n gpu_memory=(snapshot.gpu_memory_human if snapshot.gpu_memory_human is not NA else 'WDDM:N/A'),\n sm=snapshot.gpu_sm_utilization,\n command=snapshot.command))\n else:\n print(colored(' - No Running Processes', attrs=('bold',)))\n\n if separator:\n print('-' * 120)\n separator = True\n```\n\n An example monitoring script built with APIs from `nvitop`.\n\n`nvitop` provides a helper function [`take_snapshots`](https://nvitop.readthedocs.io/en/latest/api/collector.html#nvitop.take_snapshots) to retrieve the status of both GPU devices and GPU processes at once. You can type `help(nvitop.take_snapshots)` in Python REPL for detailed documentation.\n\n``` python\nIn [1]: from nvitop import take_snapshots, Device\n ...: import os\n ...: os.environ['CUDA_DEVICE_ORDER'] = 'PCI_BUS_ID'\n ...: os.environ['CUDA_VISIBLE_DEVICES'] = '1,0' # comma-separated integers or UUID strings\n\nIn [2]: take_snapshots() # equivalent to `take_snapshots(Device.all())`\nOut[2]:\nSnapshotResult(\n devices=[\n DeviceSnapshot(\n real=Device(index=0, ...),\n ...\n ),\n ...\n ],\n gpu_processes=[\n GpuProcessSnapshot(\n real=GpuProcess(pid=xxxxxx, device=Device(index=0, ...), ...),\n ...\n ),\n ...\n ]\n)\n\nIn [3]: device_snapshots, gpu_process_snapshots = take_snapshots(Device.all()) # type: Tuple[List[DeviceSnapshot], List[GpuProcessSnapshot]]\n\nIn [4]: device_snapshots, _ = take_snapshots(gpu_processes=False) # ignore process snapshots\n\nIn [5]: take_snapshots(Device.cuda.all()) # use CUDA device enumeration\nOut[5]:\nSnapshotResult(\n devices=[\n CudaDeviceSnapshot(\n real=CudaDevice(cuda_index=0, nvml_index=1, ...),\n ...\n ),\n CudaDeviceSnapshot(\n real=CudaDevice(cuda_index=1, nvml_index=0, ...),\n ...\n ),\n ],\n gpu_processes=[\n GpuProcessSnapshot(\n real=GpuProcess(pid=xxxxxx, device=CudaDevice(cuda_index=0, ...), ...),\n ...\n ),\n ...\n ]\n)\n\nIn [6]: take_snapshots(Device.cuda(1)) # only\nOut[6]:\nSnapshotResult(\n devices=[\n CudaDeviceSnapshot(\n real=CudaDevice(cuda_index=1, nvml_index=0, ...),\n ...\n )\n ],\n gpu_processes=[\n GpuProcessSnapshot(\n real=GpuProcess(pid=xxxxxx, device=CudaDevice(cuda_index=1, ...), ...),\n ...\n ),\n ...\n ]\n)\n```\n\nPlease refer to section [Low-level APIs](#low-level-apis) for more information.\n\n[`ResourceMetricCollector`](https://nvitop.readthedocs.io/en/latest/api/collector.html#nvitop.ResourceMetricCollector) is a class that collects resource metrics for host, GPUs and processes running on the GPUs. All metrics will be collected in an asynchronous manner. You can type `help(nvitop.ResourceMetricCollector)` in Python REPL for detailed documentation.\n\n``` python\nIn [1]: from nvitop import ResourceMetricCollector, Device\n ...: import os\n ...: os.environ['CUDA_DEVICE_ORDER'] = 'PCI_BUS_ID'\n ...: os.environ['CUDA_VISIBLE_DEVICES'] = '3,2,1,0' # comma-separated integers or UUID strings\n\nIn [2]: collector = ResourceMetricCollector() # log all devices and descendant processes of the current process on the GPUs\nIn [3]: collector = ResourceMetricCollector(root_pids={1}) # log all devices and all GPU processes\nIn [4]: collector = ResourceMetricCollector(devices=Device(0), root_pids={1}) # log and all GPU processes on \nIn [5]: collector = ResourceMetricCollector(devices=Device.cuda.all()) # use the CUDA ordinal\n\nIn [6]: with collector(tag=''):\n ...: # Do something\n ...: collector.collect() # -> Dict[str, float]\n# key -> '///'\n{\n '/host/cpu_percent (%)/mean': 8.967849777683456,\n '/host/cpu_percent (%)/min': 6.1,\n '/host/cpu_percent (%)/max': 28.1,\n ...,\n '/host/memory_percent (%)/mean': 21.5,\n '/host/swap_percent (%)/mean': 0.3,\n '/host/memory_used (GiB)/mean': 91.0136418208109,\n '/host/load_average (%) (1 min)/mean': 10.251427386878328,\n '/host/load_average (%) (5 min)/mean': 10.072539414569503,\n '/host/load_average (%) (15 min)/mean': 11.91126970422139,\n ...,\n '/cuda:0 (gpu:3)/memory_used (MiB)/mean': 3.875,\n '/cuda:0 (gpu:3)/memory_free (MiB)/mean': 11015.562499999998,\n '/cuda:0 (gpu:3)/memory_total (MiB)/mean': 11019.437500000002,\n '/cuda:0 (gpu:3)/memory_percent (%)/mean': 0.0,\n '/cuda:0 (gpu:3)/gpu_utilization (%)/mean': 0.0,\n '/cuda:0 (gpu:3)/memory_utilization (%)/mean': 0.0,\n '/cuda:0 (gpu:3)/fan_speed (%)/mean': 22.0,\n '/cuda:0 (gpu:3)/temperature (C)/mean': 25.0,\n '/cuda:0 (gpu:3)/power_usage (W)/mean': 19.11166264116916,\n ...,\n '/cuda:1 (gpu:2)/memory_used (MiB)/mean': 8878.875,\n ...,\n '/cuda:2 (gpu:1)/memory_used (MiB)/mean': 8182.875,\n ...,\n '/cuda:3 (gpu:0)/memory_used (MiB)/mean': 9286.875,\n ...,\n '/pid:12345/host/cpu_percent (%)/mean': 151.34342772112265,\n '/pid:12345/host/host_memory (MiB)/mean': 44749.72373447514,\n '/pid:12345/host/host_memory_percent (%)/mean': 8.675082352111717,\n '/pid:12345/host/running_time (min)': 336.23803206741576,\n '/pid:12345/cuda:1 (gpu:4)/gpu_memory (MiB)/mean': 8861.0,\n '/pid:12345/cuda:1 (gpu:4)/gpu_memory_percent (%)/mean': 80.4,\n '/pid:12345/cuda:1 (gpu:4)/gpu_memory_utilization (%)/mean': 6.711118172407917,\n '/pid:12345/cuda:1 (gpu:4)/gpu_sm_utilization (%)/mean': 48.23283397736476,\n ...,\n '/duration (s)': 7.247399162035435,\n '/timestamp': 1655909466.9981883\n}\n```\n\nThe results can be easily logged into [TensorBoard](https://github.com/tensorflow/tensorboard) or a CSV file. For example:\n\n``` python\nimport os\n\nimport torch\nimport torch.nn as nn\nimport torch.nn.functional as F\nfrom torch.utils.tensorboard import SummaryWriter\n\nfrom nvitop import CudaDevice, ResourceMetricCollector\n\ndef add_scalar_dict(writer, main_tag, tag_scalar_dict, global_step=None, walltime=None):\n for tag, scalar in tag_scalar_dict.items():\n writer.add_scalar(f'{main_tag}/{tag}', scalar, global_step=global_step, walltime=walltime)\n\n# Build networks and prepare datasets\n...\n\n# Logger and status collector\nwriter = SummaryWriter()\ncollector = ResourceMetricCollector(\n devices=CudaDevice.all(), # log all visible CUDA devices and use the CUDA ordinal\n root_pids={os.getpid()}, # only log the descendant processes of the current process\n interval=1.0, # snapshot interval for background daemon thread\n)\n\n# Start training\nglobal_step = 0\nfor epoch in range(num_epoch):\n with collector(tag='train'):\n for batch in train_dataset:\n with collector(tag='batch'):\n metrics = train(net, batch)\n global_step += 1\n add_scalar_dict(writer, 'train', metrics, global_step=global_step)\n add_scalar_dict(\n writer,\n 'resources', # tag='resources/train/batch/...'\n collector.collect(),\n global_step=global_step,\n )\n\n add_scalar_dict(\n writer,\n 'resources', # tag='resources/train/...'\n collector.collect(),\n global_step=epoch,\n )\n\n with collector(tag='validate'):\n metrics = validate(net, validation_dataset)\n add_scalar_dict(writer, 'validate', metrics, global_step=epoch)\n add_scalar_dict(\n writer,\n 'resources', # tag='resources/validate/...'\n collector.collect(),\n global_step=epoch,\n )\n```\n\nAnother example for logging into a CSV file:\n\n``` python\nimport datetime\nimport time\n\nimport pandas as pd\n\nfrom nvitop import ResourceMetricCollector\n\n# Log all devices and all GPU processes\ncollector = ResourceMetricCollector(root_pids={1}, interval=2.0)\ndf = pd.DataFrame()\n\nwith collector(tag='resources'):\n for _ in range(60):\n # Do something\n time.sleep(60)\n\n metrics = collector.collect()\n df_metrics = pd.DataFrame.from_records(metrics, index=[len(df)])\n df = pd.concat([df, df_metrics], ignore_index=True)\n # Flush to CSV file ...\n\ndf.insert(0, 'time', df['resources/timestamp'].map(datetime.datetime.fromtimestamp))\ndf.to_csv('results.csv', index=False)\n```\n\nYou can also daemonize the collector in the background using [`collect_in_background`](https://nvitop.readthedocs.io/en/latest/api/collector.html#nvitop.collect_in_background) or [`ResourceMetricCollector.daemonize`](https://nvitop.readthedocs.io/en/latest/api/collector.html#nvitop.ResourceMetricCollector.daemonize) with callback functions.\n\n``` python\nfrom nvitop import Device, ResourceMetricCollector, collect_in_background\n\nlogger = ...\n\ndef on_collect(metrics): # will be called periodically\n if logger.is_closed(): # closed manually by user\n return False\n logger.log(metrics)\n return True\n\ndef on_stop(collector): # will be called only once at stop\n if not logger.is_closed():\n logger.close() # cleanup\n\n# Record metrics to the logger in the background every 5 seconds.\n# It will collect 5-second mean/min/max for each metric.\ncollect_in_background(\n on_collect,\n ResourceMetricCollector(Device.cuda.all()),\n interval=5.0,\n on_stop=on_stop,\n)\n```\n\nor simply:\n\n```\nResourceMetricCollector(Device.cuda.all()).daemonize(\n on_collect,\n interval=5.0,\n on_stop=on_stop,\n)\n```\n\nThe full API references can be found at [https://nvitop.readthedocs.io](https://nvitop.readthedocs.io).\n\nThe [device module](https://nvitop.readthedocs.io/en/latest/api/device.html) provides:\n\n| [`Device`](https://nvitop.readthedocs.io/en/latest/api/device.html#nvitop.Device) ([index, uuid, bus_id]) | Live class of the GPU devices, different from the device snapshots. | \n| [`PhysicalDevice`](https://nvitop.readthedocs.io/en/latest/api/device.html#nvitop.PhysicalDevice) ([index, uuid, bus_id]) | Class for physical devices. | \n| [`MigDevice`](https://nvitop.readthedocs.io/en/latest/api/device.html#nvitop.MigDevice) ([index, uuid, bus_id]) | Class for MIG devices. | \n| [`CudaDevice`](https://nvitop.readthedocs.io/en/latest/api/device.html#nvitop.CudaDevice) ([cuda_index, nvml_index, uuid]) | Class for devices enumerated over the CUDA ordinal. | \n| [`CudaMigDevice`](https://nvitop.readthedocs.io/en/latest/api/device.html#nvitop.CudaMigDevice) ([cuda_index, nvml_index, uuid]) | Class for CUDA devices that are MIG devices. | \n| [`parse_cuda_visible_devices`](https://nvitop.readthedocs.io/en/latest/api/device.html#nvitop.parse_cuda_visible_devices) ([...]) | Parse the given `CUDA_VISIBLE_DEVICES` value into a list of NVML device indices. | \n| [`normalize_cuda_visible_devices`](https://nvitop.readthedocs.io/en/latest/api/device.html#nvitop.normalize_cuda_visible_devices) ([...]) | Parse the given `CUDA_VISIBLE_DEVICES` value and convert it into a comma-separated string of UUIDs. | \n\n```\nIn [1]: from nvitop import (\n ...: host,\n ...: Device, PhysicalDevice, CudaDevice,\n ...: parse_cuda_visible_devices, normalize_cuda_visible_devices\n ...: HostProcess, GpuProcess,\n ...: NA,\n ...: )\n ...: import os\n ...: os.environ['CUDA_DEVICE_ORDER'] = 'PCI_BUS_ID'\n ...: os.environ['CUDA_VISIBLE_DEVICES'] = '9,8,7,6' # comma-separated integers or UUID strings\n\nIn [2]: Device.driver_version()\nOut[2]: '525.60.11'\n\nIn [3]: Device.cuda_driver_version() # the maximum CUDA version supported by the driver (can be different from the CUDA Runtime version)\nOut[3]: '12.0'\n\nIn [4]: Device.cuda_runtime_version() # the CUDA Runtime version\nOut[4]: '11.8'\n\nIn [5]: Device.count()\nOut[5]: 10\n\nIn [6]: CudaDevice.count() # or `Device.cuda.count()`\nOut[6]: 4\n\nIn [7]: all_devices = Device.all() # all devices on board (physical device)\n ...: nvidia0, nvidia1 = Device.from_indices([0, 1]) # from physical device indices\n ...: all_devices\nOut[7]: [\n PhysicalDevice(index=0, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n PhysicalDevice(index=1, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n PhysicalDevice(index=2, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n PhysicalDevice(index=3, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n PhysicalDevice(index=4, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n PhysicalDevice(index=5, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n PhysicalDevice(index=6, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n PhysicalDevice(index=7, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n PhysicalDevice(index=8, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n PhysicalDevice(index=9, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB)\n]\n\nIn [8]: # NOTE: The function results might be different between calls when the `CUDA_VISIBLE_DEVICES` environment variable has been modified\n ...: cuda_visible_devices = Device.from_cuda_visible_devices() # from the `CUDA_VISIBLE_DEVICES` environment variable\n ...: cuda0, cuda1 = Device.from_cuda_indices([0, 1]) # from CUDA device indices (might be different from physical device indices if `CUDA_VISIBLE_DEVICES` is set)\n ...: cuda_visible_devices = CudaDevice.all() # shortcut to `Device.from_cuda_visible_devices()`\n ...: cuda_visible_devices = Device.cuda.all() # `Device.cuda` is aliased to `CudaDevice`\n ...: cuda_visible_devices\nOut[8]: [\n CudaDevice(cuda_index=0, nvml_index=9, name=\"NVIDIA GeForce RTX 2080 Ti\", total_memory=11019MiB),\n CudaDevice(cuda_index=1, nvml_index=8, name=\"NVIDIA GeForce RTX 2080 Ti\", total_memory=11019MiB),\n CudaDevice(cuda_index=2, nvml_index=7, name=\"NVIDIA GeForce RTX 2080 Ti\", total_memory=11019MiB),\n CudaDevice(cuda_index=3, nvml_index=6, name=\"NVIDIA GeForce RTX 2080 Ti\", total_memory=11019MiB)\n]\n\nIn [9]: nvidia0 = Device(0) # from device index (or `Device(index=0)`)\n ...: nvidia0\nOut[9]: PhysicalDevice(index=0, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB)\n\nIn [10]: nvidia1 = Device(uuid='GPU-01234567-89ab-cdef-0123-456789abcdef') # from UUID string (or just `Device('GPU-xxxxxxxx-...')`)\n ...: nvidia2 = Device(bus_id='00000000:06:00.0') # from PCI bus ID\n ...: nvidia1\nOut[10]: PhysicalDevice(index=1, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB)\n\nIn [11]: cuda0 = CudaDevice(0) # from CUDA device index (equivalent to `CudaDevice(cuda_index=0)`)\n ...: cuda1 = CudaDevice(nvml_index=8) # from physical device index\n ...: cuda3 = CudaDevice(uuid='GPU-xxxxxxxx-...') # from UUID string\n ...: cuda4 = Device.cuda(4) # `Device.cuda` is aliased to `CudaDevice`\n ...: cuda0\nOut[11]:\nCudaDevice(cuda_index=0, nvml_index=9, name=\"NVIDIA GeForce RTX 2080 Ti\", total_memory=11019MiB)\n\nIn [12]: nvidia0.memory_used() # in bytes\nOut[12]: 9293398016\n\nIn [13]: nvidia0.memory_used_human()\nOut[13]: '8862MiB'\n\nIn [14]: nvidia0.gpu_utilization() # in percentage\nOut[14]: 5\n\nIn [15]: nvidia0.processes() # type: Dict[int, GpuProcess]\nOut[15]: {\n 52059: GpuProcess(pid=52059, gpu_memory=7885MiB, type=C, device=PhysicalDevice(index=0, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=52059, name='ipython3', status='sleeping', started='14:31:22')),\n 53002: GpuProcess(pid=53002, gpu_memory=967MiB, type=C, device=PhysicalDevice(index=0, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=53002, name='python', status='running', started='14:31:59'))\n}\n\nIn [16]: nvidia1_snapshot = nvidia1.as_snapshot()\n ...: nvidia1_snapshot\nOut[16]: PhysicalDeviceSnapshot(\n real=PhysicalDevice(index=1, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n bus_id='00000000:05:00.0',\n compute_mode='Default',\n clock_infos=ClockInfos(graphics=1815, sm=1815, memory=6800, video=1680), # in MHz\n clock_speed_infos=ClockSpeedInfos(current=ClockInfos(graphics=1815, sm=1815, memory=6800, video=1680), max=ClockInfos(graphics=2100, sm=2100, memory=7000, video=1950)), # in MHz\n cuda_compute_capability=(7, 5),\n current_driver_model='N/A',\n decoder_utilization=0, # in percentage\n display_active='Disabled',\n display_mode='Disabled',\n encoder_utilization=0, # in percentage\n fan_speed=22, # in percentage\n gpu_utilization=17, # in percentage (NOTE: this is the utilization rate of SMs, i.e. GPU percent)\n index=1,\n max_clock_infos=ClockInfos(graphics=2100, sm=2100, memory=7000, video=1950), # in MHz\n memory_clock=6800, # in MHz\n memory_free=10462232576, # in bytes\n memory_free_human='9977MiB',\n memory_info=MemoryInfo(total=11554717696, free=10462232576, used=1092485120) # in bytes\n memory_percent=9.5, # in percentage (NOTE: this is the percentage of used GPU memory)\n memory_total=11554717696, # in bytes\n memory_total_human='11019MiB',\n memory_usage='1041MiB / 11019MiB',\n memory_used=1092485120, # in bytes\n memory_used_human='1041MiB',\n memory_utilization=7, # in percentage (NOTE: this is the utilization rate of GPU memory bandwidth)\n mig_mode='N/A',\n name='GeForce RTX 2080 Ti',\n pcie_rx_throughput=1000, # in KiB/s\n pcie_rx_throughput_human='1000KiB/s',\n pcie_throughput=ThroughputInfo(tx=1000, rx=1000), # in KiB/s\n pcie_tx_throughput=1000, # in KiB/s\n pcie_tx_throughput_human='1000KiB/s',\n performance_state='P2',\n persistence_mode='Disabled',\n power_limit=250000, # in milliwatts (mW)\n power_status='66W / 250W', # in watts (W)\n power_usage=66051, # in milliwatts (mW)\n sm_clock=1815, # in MHz\n temperature=39, # in Celsius\n total_volatile_uncorrected_ecc_errors='N/A',\n utilization_rates=UtilizationRates(gpu=17, memory=7, encoder=0, decoder=0), # in percentage\n uuid='GPU-01234567-89ab-cdef-0123-456789abcdef',\n)\n\nIn [17]: nvidia1_snapshot.memory_percent # snapshot uses properties instead of function calls\nOut[17]: 9.5\n\nIn [18]: nvidia1_snapshot['memory_info'] # snapshot also supports `__getitem__` by string\nOut[18]: MemoryInfo(total=11554717696, free=10462232576, used=1092485120)\n\nIn [19]: nvidia1_snapshot.bar1_memory_info # snapshot will automatically retrieve not presented attributes from `real`\nOut[19]: MemoryInfo(total=268435456, free=257622016, used=10813440)\n```\n\n**NOTE:** Some entry values may be `'N/A'` (type: [`NaType`](https://nvitop.readthedocs.io/en/latest/index.html#nvitop.NaType), a subclass of `str`) when the corresponding resources are not applicable. The [` NA`](https://nvitop.readthedocs.io/en/latest/index.html#nvitop.NA) value supports arithmetic operations. It acts like `math.nan: float`.\n\n``` python\n>>> from nvitop import NA\n>>> NA\n'N/A'\n\n>>> 'memory usage: {}'.format(NA) # NA is an instance of `str`\n'memory usage: N/A'\n>>> NA.lower() # NA is an instance of `str`\n'n/a'\n>>> NA.ljust(5) # NA is an instance of `str`\n'N/A '\n>>> NA + 'str' # string contamination if the operand is a string\n'N/Astr'\n\n>>> float(NA) # explicit conversion to float (`math.nan`)\nnan\n>>> NA + 1 # auto-casting to float if the operand is a number\nnan\n>>> NA * 1024 # auto-casting to float if the operand is a number\nnan\n>>> NA / (1024 * 1024) # auto-casting to float if the operand is a number\nnan\n```\n\nYou can use `entry != 'N/A'` conditions to avoid exceptions. It's safe to use `float(entry)` for numbers while `NaType` will be converted to `math.nan`. For example:\n\n```\nmemory_used: Union[int, NaType] = device.memory_used() # memory usage in bytes or `'N/A'`\nmemory_used_in_mib: float = float(memory_used) / (1 << 20) # memory usage in Mebibytes (MiB) or `math.nan`\n```\n\nIt's safe to compare `NaType` with numbers, but `NaType` is always larger than any number:\n\n```\ndevices_by_used_memory = sorted(Device.all(), key=Device.memory_used, reverse=True) # it's safe to compare `'N/A'` with numbers\ndevices_by_free_memory = sorted(Device.all(), key=Device.memory_free, reverse=True) # please add `memory_free != 'N/A'` checks if sort in descending order here\n```\n\nSee [`nvitop.NaType`](https://nvitop.readthedocs.io/en/latest/apis/index.html#nvitop.NaType) documentation for more details.\n\nThe [process module](https://nvitop.readthedocs.io/en/latest/api/process.html) provides:\n\n| [`HostProcess`](https://nvitop.readthedocs.io/en/latest/api/process.html#nvitop.HostProcess) ([pid]) | Represents an OS process with the given PID. | \n| [`GpuProcess`](https://nvitop.readthedocs.io/en/latest/api/process.html#nvitop.GpuProcess) (pid, device[, gpu_memory, ...]) | Represents a process with the given PID running on the given GPU device. | \n| [`command_join`](https://nvitop.readthedocs.io/en/latest/api/process.html#nvitop.command_join) (cmdline) | Returns a shell-escaped string from command line arguments. | \n\n```\nIn [20]: processes = nvidia1.processes() # type: Dict[int, GpuProcess]\n ...: processes\nOut[20]: {\n 23266: GpuProcess(pid=23266, gpu_memory=1031MiB, type=C, device=Device(index=1, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=23266, name='python3', status='running', started='2021-05-10 21:02:40'))\n}\n\nIn [21]: process = processes[23266]\n ...: process\nOut[21]: GpuProcess(pid=23266, gpu_memory=1031MiB, type=C, device=Device(index=1, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=23266, name='python3', status='running', started='2021-05-10 21:02:40'))\n\nIn [22]: process.status() # GpuProcess will automatically inherit attributes from GpuProcess.host\nOut[22]: 'running'\n\nIn [23]: process.cmdline() # type: List[str]\nOut[23]: ['python3', 'rllib_train.py']\n\nIn [24]: process.command() # type: str\nOut[24]: 'python3 rllib_train.py'\n\nIn [25]: process.cwd() # GpuProcess will automatically inherit attributes from GpuProcess.host\nOut[25]: '/home/xxxxxx/Projects/xxxxxx'\n\nIn [26]: process.gpu_memory_human()\nOut[26]: '1031MiB'\n\nIn [27]: process.as_snapshot()\nOut[27]: GpuProcessSnapshot(\n real=GpuProcess(pid=23266, gpu_memory=1031MiB, type=C, device=PhysicalDevice(index=1, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=23266, name='python3', status='running', started='2021-05-10 21:02:40')),\n cmdline=['python3', 'rllib_train.py'],\n command='python3 rllib_train.py',\n compute_instance_id='N/A',\n cpu_percent=98.5, # in percentage\n device=PhysicalDevice(index=1, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB),\n gpu_encoder_utilization=0, # in percentage\n gpu_decoder_utilization=0, # in percentage\n gpu_instance_id='N/A',\n gpu_memory=1081081856, # in bytes\n gpu_memory_human='1031MiB',\n gpu_memory_percent=9.4, # in percentage (NOTE: this is the percentage of used GPU memory)\n gpu_memory_utilization=5, # in percentage (NOTE: this is the utilization rate of GPU memory bandwidth)\n gpu_sm_utilization=0, # in percentage (NOTE: this is the utilization rate of SMs, i.e. GPU percent)\n host=HostProcessSnapshot(\n real=HostProcess(pid=23266, name='python3', status='running', started='2021-05-10 21:02:40'),\n cmdline=['python3', 'rllib_train.py'],\n command='python3 rllib_train.py',\n cpu_percent=98.5, # in percentage\n host_memory=9113627439, # in bytes\n host_memory_human='8691MiB',\n is_running=True,\n memory_percent=1.6849018430285683, # in percentage\n name='python3',\n running_time=datetime.timedelta(days=1, seconds=80013, microseconds=470024),\n running_time_human='46:13:33',\n running_time_in_seconds=166413.470024,\n status='running',\n username='panxuehai',\n ),\n host_memory=9113627439, # in bytes\n host_memory_human='8691MiB',\n is_running=True,\n memory_percent=1.6849018430285683, # in percentage (NOTE: this is the percentage of used host memory)\n name='python3',\n pid=23266,\n running_time=datetime.timedelta(days=1, seconds=80013, microseconds=470024),\n running_time_human='46:13:33',\n running_time_in_seconds=166413.470024,\n status='running',\n type='C', # 'C' for Compute / 'G' for Graphics / 'C+G' for Both\n username='panxuehai',\n)\n\nIn [28]: process.uids() # GpuProcess will automatically inherit attributes from GpuProcess.host\nOut[28]: puids(real=1001, effective=1001, saved=1001)\n\nIn [29]: process.kill() # GpuProcess will automatically inherit attributes from GpuProcess.host\n\nIn [30]: list(map(Device.processes, all_devices)) # all processes\nOut[30]: [\n {\n 52059: GpuProcess(pid=52059, gpu_memory=7885MiB, type=C, device=PhysicalDevice(index=0, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=52059, name='ipython3', status='sleeping', started='14:31:22')),\n 53002: GpuProcess(pid=53002, gpu_memory=967MiB, type=C, device=PhysicalDevice(index=0, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=53002, name='python', status='running', started='14:31:59'))\n },\n {},\n {},\n {},\n {},\n {},\n {},\n {},\n {\n 84748: GpuProcess(pid=84748, gpu_memory=8975MiB, type=C, device=PhysicalDevice(index=8, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=84748, name='python', status='running', started='11:13:38'))\n },\n {\n 84748: GpuProcess(pid=84748, gpu_memory=8341MiB, type=C, device=PhysicalDevice(index=9, name=\"GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=84748, name='python', status='running', started='11:13:38'))\n }\n]\n\nIn [31]: this = HostProcess(os.getpid())\n ...: this\nOut[31]: HostProcess(pid=35783, name='python', status='running', started='19:19:00')\n\nIn [32]: this.cmdline() # type: List[str]\nOut[32]: ['python', '-c', 'import IPython; IPython.terminal.ipapp.launch_new_instance()']\n\nIn [33]: this.command() # not simply `' '.join(cmdline)` but quotes are added\nOut[33]: 'python -c \"import IPython; IPython.terminal.ipapp.launch_new_instance()\"'\n\nIn [34]: this.memory_info()\nOut[34]: pmem(rss=83988480, vms=343543808, shared=12079104, text=8192, lib=0, data=297435136, dirty=0)\n\nIn [35]: import cupy as cp\n ...: x = cp.zeros((10000, 1000))\n ...: this = GpuProcess(os.getpid(), cuda0) # construct from `GpuProcess(pid, device)` explicitly rather than calling `device.processes()`\n ...: this\nOut[35]: GpuProcess(pid=35783, gpu_memory=N/A, type=N/A, device=CudaDevice(cuda_index=0, nvml_index=9, name=\"NVIDIA GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=35783, name='python', status='running', started='19:19:00'))\n\nIn [36]: this.update_gpu_status() # update used GPU memory from new driver queries\nOut[36]: 267386880\n\nIn [37]: this\nOut[37]: GpuProcess(pid=35783, gpu_memory=255MiB, type=C, device=CudaDevice(cuda_index=0, nvml_index=9, name=\"NVIDIA GeForce RTX 2080 Ti\", total_memory=11019MiB), host=HostProcess(pid=35783, name='python', status='running', started='19:19:00'))\n\nIn [38]: id(this) == id(GpuProcess(os.getpid(), cuda0)) # IMPORTANT: the instance will be reused while the process is running\nOut[38]: True\n```\n\n##### Host (inherited from [psutil](https://github.com/giampaolo/psutil))\n\n```\nIn [39]: host.cpu_count()\nOut[39]: 88\n\nIn [40]: host.cpu_percent()\nOut[40]: 18.5\n\nIn [41]: host.cpu_times()\nOut[41]: scputimes(user=2346377.62, nice=53321.44, system=579177.52, idle=10323719.85, iowait=28750.22, irq=0.0, softirq=11566.87, steal=0.0, guest=0.0, guest_nice=0.0)\n\nIn [42]: host.load_average()\nOut[42]: (14.88, 17.8, 19.91)\n\nIn [43]: host.virtual_memory()\nOut[43]: svmem(total=270352478208, available=192275968000, percent=28.9, used=53350518784, free=88924037120, active=125081112576, inactive=44803993600, buffers=37006450688, cached=91071471616, shared=23820632064, slab=8200687616)\n\nIn [44]: host.memory_percent()\nOut[44]: 28.9\n\nIn [45]: host.swap_memory()\nOut[45]: sswap(total=65534947328, used=475136, free=65534472192, percent=0.0, sin=2404139008, sout=4259434496)\n\nIn [46]: host.swap_percent()\nOut[46]: 0.0\n```\n\nExample output of `nvitop -1`:\n\nExample output of `nvitop`:\n\n| Full | Compact | \n\nTree-view screen (shortcut: `t`) for GPU processes and their ancestors:\n\n**NOTE:** The process tree is built in backward order (recursively back to the tree root). Only GPU processes along with their children and ancestors (parents and grandparents ...) will be shown. Not all running processes will be displayed.\n\nEnvironment variable screen (shortcut: `e`):\n\nSpectrum-like bar charts (with option `--colorful`):\n\nSee [CHANGELOG.md](https://github.com/XuehaiPan/nvitop/blob/HEAD/CHANGELOG.md).\n\nThe source code of `nvitop` is dual-licensed by the **Apache License, Version 2.0 (Apache-2.0)** and **GNU General Public License, Version 3 (GPL-3.0)**. The `nvitop` CLI is released under the **GPL-3.0** license while the remaining part of `nvitop` is released under the **Apache-2.0** license. The license files can be found at [LICENSE](https://github.com/XuehaiPan/nvitop/blob/HEAD/LICENSE) (Apache-2.0) and [COPYING](https://github.com/XuehaiPan/nvitop/blob/HEAD/COPYING) (GPL-3.0).\n\nThe source code is organized as:\n\n```\nnvitop (GPL-3.0)\n├── __init__.py (Apache-2.0)\n├── version.py (Apache-2.0)\n├── api (Apache-2.0)\n│ ├── LICENSE (Apache-2.0)\n│ └── * (Apache-2.0)\n├── select.py (Apache-2.0)\n├── __main__.py (GPL-3.0)\n├── cli.py (GPL-3.0)\n└── tui (GPL-3.0)\n ├── COPYING (GPL-3.0)\n └── * (GPL-3.0)\n```\n\nPlease feel free to use `nvitop` as a dependency for your own projects. The following Python import statements are permitted:\n\n``` python\nimport nvitop\nimport nvitop as alias\nimport nvitop.api as api\nimport nvitop.device as device\nfrom nvitop import *\nfrom nvitop.api import *\nfrom nvitop import Device, ResourceMetricCollector\n```\n\nThe public APIs from `nvitop` are released under the **Apache License, Version 2.0 (Apache-2.0)**. The original license files can be found at [LICENSE](https://github.com/XuehaiPan/nvitop/blob/HEAD/LICENSE), [nvitop/api/LICENSE](https://github.com/XuehaiPan/nvitop/blob/HEAD/nvitop/api/LICENSE).\n\nThe CLI of `nvitop` is released under the **GNU General Public License, Version 3 (GPL-3.0)**. The original license files can be found at [COPYING](https://github.com/XuehaiPan/nvitop/blob/HEAD/COPYING) and [nvitop/tui/COPYING](https://github.com/XuehaiPan/nvitop/blob/HEAD/nvitop/tui/COPYING). If you dynamically load the source code of `nvitop`'s CLI or TUI:\n\n``` python\nfrom nvitop import cli\nfrom nvitop import tui\nimport nvitop.cli\nimport nvitop.tui\n```\n\nyour source code should also be released under the GPL-3.0 License.\n\nIf you want to add or modify some features of `nvitop`'s CLI, or copy some source code of `nvitop`'s CLI into your own code, the source code should also be released under the GPL-3.0 License (as `nvitop` contains some modified source code from [ranger](https://github.com/ranger/ranger) under the GPL-3.0 License).", "url": "https://wpnews.pro/news/nvitop-a-better-top-for-nvidia-gpus", "canonical_source": "https://github.com/XuehaiPan/nvitop", "published_at": "2026-09-23 07:24:33+00:00", "updated_at": "2026-09-23 07:54:28.194371+00:00", "lang": "en", "topics": ["ai-infrastructure", "developer-tools", "ai-tools"], "entities": ["Nvitop", "NVIDIA", "nvisel", "NVML", "nvidia-ml-py", "psutil", "nvidia-smi", "Grafana"], "alternates": {"html": "https://wpnews.pro/news/nvitop-a-better-top-for-nvidia-gpus", "markdown": "https://wpnews.pro/news/nvitop-a-better-top-for-nvidia-gpus.md", "text": "https://wpnews.pro/news/nvitop-a-better-top-for-nvidia-gpus.txt", "jsonld": "https://wpnews.pro/news/nvitop-a-better-top-for-nvidia-gpus.jsonld"}}