Mockup Nvidia GPUs on Linux systems

Mock nvidia gpus in Linux for monitoring software that reads NVIDIA telemetry through NVML or nvidia-smi

. It does not emulate CUDA, PCI hardware, kernel ioctls, MIG provisioning, or GPU computation.

make
make test

Requirements: Linux, gcc

, make

, Python 3.

export MOCK_NVIDIA_STATE="$PWD/scenarios/loaded.json"
export LD_LIBRARY_PATH="$PWD/build${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
export PATH="$PWD/bin:$PATH"

nvidia-smi
nvidia-smi --query-gpu=uuid,name,utilization.gpu,memory.used,memory.total,temperature.gpu,power.draw,power.limit --format=csv,noheader,nounits
python3 examples/read_nvml.py

Run the diagnostic before testing a third-party program:

./bin/diagnose-

The build provides all common names: libnvidia-ml.so.1

, libnvidia-ml.so

, libnvml.so.1

, and libnvml.so

. NVTOP currently documents that it loads libnvml.so

, rather than the canonical NVIDIA filename.

For an application linked to NVML:

LD_LIBRARY_PATH="$PWD/build" MOCK_NVIDIA_STATE="$PWD/scenarios/thermal.json" ./monitor

If the application loads an absolute path, mount build/libnvidia-ml.so.1

over that library inside an isolated test container. Never replace the host driver library.

LD_LIBRARY_PATH

is commonly removed by sudo

and ignored by confined Snap or setuid applications. A systemd service also needs both LD_LIBRARY_PATH

and MOCK_NVIDIA_STATE

in its unit environment. Run the tool directly as the same user while establishing basic compatibility.

Point MOCK_NVIDIA_STATE

at a scenario file to render a different operating face through nvidia-smi

or the NVML library. Each mode is independent and can be swapped at runtime.

scenarios/idle.json

— a GPU at rest. Low GPU and memory utilization, an idle temperature, fans near their floor, and a minimal power draw. Clocks sit at their baseline speed.

scenarios/loaded.json

— a GPU running a busy compute workload. High GPU utilization, boosted graphics and memory clocks, and most of VRAM consumed.

scenarios/thermal.json

— a GPU at its thermal and power ceiling. Temperature approaches maximum, fans run at 100%, power draw is capped at the limit, the performance state sags, and ECC reports errors.

scenarios/4gpus.json

— four GPUs under a mixed workload: two H100s in a busy state and two L40S blades, one loaded and one idle. GPU order in the array determines the NVML index.

The library reloads the JSON file when its modification time changes. Switch scenarios without restarting the monitored process:

cp scenarios/thermal.json /tmp/mock-gpu.json
export MOCK_NVIDIA_STATE=/tmp/mock-gpu.json

Supported state fields are demonstrated in scenarios/loaded.json

. Memory is specified in MiB and power in watts. NVML returns bytes and milliwatts as the real API does.

For multiple GPUs, place one to eight device objects in gpus

:

{
  "gpus": [
    {
      "name": "NVIDIA H100 80GB HBM3",
      "uuid": "GPU-FAKE-0001",
      "pci_bus_id": "00000000:01:00.0",
      "gpu_utilization_percent": 94,
      "vram_total_mib": 81559,
      "vram_used_mib": 74200,
      "temperature_c": 78,
      "power_draw_w": 610,
      "power_limit_w": 700
    },
    {
      "name": "NVIDIA L40S",
      "uuid": "GPU-FAKE-0002",
      "pci_bus_id": "00000000:02:00.0",
      "gpu_utilization_percent": 20,
      "vram_total_mib": 46068,
      "vram_used_mib": 9000,
      "temperature_c": 51,
      "power_draw_w": 160,
      "power_limit_w": 350
    }
  ]
}

See scenarios/4gpus.json

for a complete mixed-load example. GPU order in the array determines the NVML index. UUID and PCI bus ID must be unique.

• initialization and shutdown
• device count and handles by index or UUID
• name, UUID, serial and PCI information
• utilization, memory, temperature and fan speed
• power draw and power limit
• graphics, SM and memory clocks
• performance state and compute mode
• ECC mode and aggregate error count
• running compute process count
• driver and NVML versions

Unsupported calls are absent. Add any required function to src/mock_nvml.c

using the same state and NVIDIA NVML function signature.

This package validates collectors, dashboards, alerts and recommendation logic. It cannot validate the NVIDIA kernel driver, CUDA workloads, PCI discovery, DCGM diagnostics, ECC hardware, throttling behavior or real process accounting.

Support the project and other projects like this by supporting the creator, feel free to reach out for other ways to contribute.

• EVM: 0x6e8e3c2b31424266e7cff59e910df1587c317427

(ERC-20, BEP-20, TRC-20, AVAX-C, SPL, MATIC, POL, ARB, BASE, TON) - BTC: bc1qzzvcguvqjc6qhwe2y5vy38w2zke7hksukjhm68

• LTC: MPfm5QLKH1r9XxgWmH75Gyps4LDfX5c53L

• SOL: GEaCMpnyM8tB5BU4RMuLm6tgMr3q9FgMHodxDxxAGby

• DOGE: DPkJheSBTTkFv9oxnEwGsfvrcCvEWDVhVY