nvidia-smi --query-gpu: Scriptable GPU Fields

nvidia-smi --query-gpu selects specific GPU properties and prints them as CSV, so a script can read them without parsing the human table.

The default table is for humans. For gates and metrics you want --query-gpu with --format=csv, which gives one clean line per GPU.

What it does

nvidia-smi --query-gpu=<fields> --format=csv queries NVML for the named per-GPU fields and prints them as comma-separated values, one row per GPU. It pairs with --format options to drop the header and units for easy parsing.

Common usage

Terminal

nvidia-smi --query-gpu=index,name,memory.total,memory.used --format=csv
# no header, no units, just numbers
nvidia-smi --query-gpu=utilization.gpu,memory.used \
  --format=csv,noheader,nounits
# list the valid field names
nvidia-smi --help-query-gpu

Options

Field / flag	What it does
name	GPU product name
memory.total / memory.used / memory.free	Framebuffer memory in MiB
utilization.gpu	Percent of time the GPU was busy
temperature.gpu	GPU core temperature (C)
driver_version	Installed driver version
--format=csv,noheader,nounits	Drop the header row and unit suffixes

In CI

Use --format=csv,noheader,nounits so a test can compare raw integers, e.g. assert memory.total is above a threshold before scheduling a large batch. Run nvidia-smi --help-query-gpu to see every valid field for the installed driver.

Common errors in CI

"Field \"foo\" is not a valid field to query." means a typo or a field the driver version does not support; check nvidia-smi --help-query-gpu. A field that prints "[N/A]" or "[Not Supported]" is valid but unavailable on that GPU (common for power/utilization on some datacenter or virtualized GPUs), so guard scripts against non-numeric values.