nvctl

A fast, safe NVIDIA GPU control tool written in Rust. Manage fan speeds, power limits, and thermal settings via NVML.

Features

CLI Tool

• Fan Control - Manual speed control and automatic fan curves
• Power Management - Set and monitor GPU power limits with constraint validation
• Thermal Monitoring - Real-time temperature and threshold management
• Acoustic Limiting - GPU temperature targets for noise control
• Health Monitoring - Comprehensive GPU health scoring with issue detection
• Process Monitoring - List GPU processes with memory usage and filtering
• Workload Automation - Switch saved profiles when games, renderers, or CUDA jobs appear
• Alert System - Configurable alerts for temperature, power, and hardware issues
• Advanced Metrics - ECC errors, PCIe bandwidth, memory temperature, video encoder/decoder
• Multi-GPU Support - Target by index, name, or UUID
• Multiple Output Formats - Table, JSON, and compact output
• Dry-Run Mode - Preview changes before applying
• Transactional Profiles - Validate every GPU first and restore the original state on exit or failure
• Daemon Mode - Continuous control loop with custom fan curves
• Configuration Files - TOML-based persistent configuration

GUI Application (nvctl-gui)

• Glossy Glassmorphism Design - Modern, vibrant interface with glass effects
• Real-time Monitoring - Live gauges for temperature, fan speed, power, and utilization
• Advanced Metrics Dashboard - ECC errors, PCIe bandwidth, memory temp, video encoder/decoder
• Health Score Widget - Visual GPU health gauge with component breakdown
• Interactive Fan Curves - Drag-and-drop curve editor with visual feedback
• Multi-GPU Dashboard - Overview of all GPUs with link/unlink control
• Profile System - Save and load configuration profiles
• Multi-Series Graphs - Historical tracking of temperature, power, and performance
• Per-Fan Control - Individual fan speed control with cooler target info

Installation

From Source

git clone https://github.com/mqasimca/nvctl.git
cd nvctl

# Build CLI tool
cargo build --release
sudo cp target/release/nvctl /usr/local/bin/

# Build GUI (optional)
cargo build --release --package nvctl-gui
sudo cp target/release/nvctl-gui /usr/local/bin/

Requirements

• NVIDIA GPU with proprietary driver installed
• NVIDIA driver version 520+ recommended
• Linux with libnvidia-ml.so available (included with nvidia-utils)

Quick Start

# List all GPUs
nvctl list

# Show GPU information
nvctl info --all

# Check GPU health
nvctl health

# List processes using GPU
nvctl processes --top 5

# Check fan status
nvctl fan status

# Set fan to manual mode and 75% speed
sudo nvctl fan policy manual
sudo nvctl fan speed 75

# Set power limit to 250W
sudo nvctl power limit 250

# View alert rules
nvctl alerts rules

# Preview changes without applying
nvctl --dry-run fan speed 100

GUI Application

Launch the graphical interface for visual GPU control:

# Run GUI (release mode for smooth animations)
make gui

# Or directly
nvctl-gui

GUI Features

• Dashboard - Real-time gauges with glassmorphic design
  • Temperature, fan speed, power, and utilization gauges
  • ECC memory error tracking
  • PCIe bandwidth and link status visualization
  • Memory temperature monitoring (GDDR6X)
  • Video encoder/decoder utilization
  • GPU health score with component breakdown
  • Quick stats (clocks, VRAM, P-state)
• Fan Control - Interactive fan curve editor with drag-and-drop points
• Power Control - Slider-based power limit adjustment with constraints display
• Thermal Control - Acoustic temperature-limit monitoring and adjustment on supported GPUs
• Profiles - Save/load/delete configuration profiles
• Settings - System information, keyboard shortcuts, and detected GPU status

GUI Make Commands

make gui          # Run GUI (release mode)
make gui-dev      # Run GUI (debug mode)
make gui-check    # Check GUI code (fmt + clippy)
make gui-test     # Run GUI tests
make gui-build    # Build GUI release binary

Screenshots

Dashboard

Real-time monitoring with all GPU metrics at a glance.

Fan Control

Interactive fan curve editor with drag-and-drop temperature/speed points.

Power Management

Precise power limit control with visual feedback.

Thermal Control

Acoustic temperature-limit monitoring and adjustment on supported GPUs.

Profile Management

Save and load GPU configuration profiles.

Settings

System information, shortcuts, detected GPUs, and the configured polling interval.

CLI Usage

Listing GPUs

nvctl list
nvctl list --format json

GPU Information

nvctl info                    # All available details (default)
nvctl info --all              # Explicitly request all details
nvctl info --fan              # Fan info only
nvctl info --power            # Power info only
nvctl info --thermal          # Thermal info only
nvctl info --ecc              # ECC memory errors
nvctl info --pcie             # PCIe bandwidth and link status
nvctl info --memory-temp      # Memory temperature (GDDR6X)
nvctl info --video            # Video encoder/decoder utilization
nvctl --gpu 0 info --all      # Specific GPU
nvctl --gpu-name "RTX 5080" info  # By name

Fan Control

# Check status
nvctl fan status

# Set control policy
sudo nvctl fan policy manual   # Enable manual control
sudo nvctl fan policy auto     # Return to automatic

# Set fan speed (switches the target fan to manual policy)
sudo nvctl fan speed 50        # All fans to 50%
sudo nvctl fan speed 80 --fan-index 0  # Specific fan

# Dry run
nvctl --dry-run fan speed 100

Power Management

# Check current power status
nvctl power status

# Set power limit
sudo nvctl power limit 250     # Set to 250W

# Dry run
nvctl --dry-run power limit 300

Thermal Control

Control the acoustic temperature limit. The GPU throttles performance to maintain the target temperature (same as GeForce Experience temperature target).

# Check thermal status
nvctl thermal status

# Set acoustic temperature limit
sudo nvctl thermal limit 80

# Dry run
nvctl --dry-run thermal limit 75

Note: Not all GPUs support acoustic temperature limits.

Health Monitoring

Check overall GPU health with component-specific scoring:

# Check GPU health
nvctl health

# JSON output for monitoring
nvctl health --format json

Health scoring covers:

• Thermal Health - Temperature vs. thresholds
• Power Health - Power usage efficiency
• Memory Health - ECC errors and utilization
• Performance Health - Utilization and throttling
• PCIe Health - Link status and errors

Process Monitoring

List processes running on the GPU with memory usage:

# List all processes
nvctl processes

# Show top 5 by memory
nvctl processes --top 5

# Sort by PID instead of memory
nvctl processes --sort-pid

# Filter by process type
nvctl processes --process-type graphics
nvctl processes --process-type compute
nvctl processes --process-type both  # Hybrid graphics+compute processes

# JSON output
nvctl processes --format json

Process types:

• Graphics - Display/rendering workloads
• Compute - CUDA/OpenCL compute tasks
• Graphics+Compute - Hybrid workloads

Workload-Aware Profiles

The CLI uses the same profile files as the GUI in ~/.config/nvctl/profiles. Profiles can contain GPU-specific settings keyed by UUID and/or a default entry. List and inspect them with:

nvctl profile list
nvctl profile show Performance

Run one profile in the foreground. Fan curves continue to update while the process runs, and the power limit, acoustic target, fan policies, and manual fan speeds captured at startup are restored on Ctrl-C or any error:

# Preview one full apply/restore cycle without changing the GPU
nvctl --dry-run profile run Performance --single-use

# Keep the profile active until Ctrl-C
sudo nvctl profile run Performance

Workload automation evaluates case-insensitive process globs reported by NVML. The highest-priority matching rule wins; configuration order breaks priority ties. Minimum-match durations, release delay, and transition cooldown prevent rapid switching:

# Explain the current decision without applying anything
nvctl auto explain

# Test one decision and restoration cycle
nvctl --dry-run auto run --single-use --force

# Run until Ctrl-C (requires automation.enabled = true)
sudo nvctl auto run

# Inspect a running process or its last decision
nvctl auto status

Only one automation process can run at a time. Mutating CLI commands also take per-GPU ownership locks, so profile sessions, automation, the control loop, and one-shot fan/power/thermal writes cannot race on the same GPU. auto status keeps an explicit restoration error visible if the original GPU state could not be restored. Automation runs in the foreground so a service manager such as systemd can supervise it. See examples/automation/nvctl.toml for a complete RTX 5080 example with Quiet and Performance power profiles. Profile power values are stored in milliwatts because that is NVML's native unit; 300000 means 300 W. Check your own supported range with nvctl power status before changing those values.

Alert System

Monitor GPU metrics with configurable alerts:

# List configured alert rules
nvctl alerts rules

# List active alerts
nvctl alerts list

# Start alert monitoring daemon
nvctl alerts start

# Stop alert daemon
nvctl alerts stop

# Acknowledge an alert
nvctl alerts ack <alert-id>

# Silence an alert
nvctl alerts silence <alert-id>

# Clear resolved alerts
nvctl alerts clear

# Test alert configuration
nvctl alerts test

Default alert rules (in ~/.config/nvctl/alerts.toml):

• High GPU temperature (>80°C for 30s)
• Critical temperature (>85°C for 10s)
• Emergency temperature (>90°C, shutdown risk)
• High power usage (>95% for 60s)
• ECC uncorrectable errors detected
• PCIe link errors/replay counter

Daemon Mode (Fan Curves)

Run a continuous control loop with custom fan curves:

sudo nvctl control \
  --speed-pair 40:30 \
  --speed-pair 50:40 \
  --speed-pair 60:50 \
  --speed-pair 70:70 \
  --speed-pair 80:100 \
  --interval 5

This sets:

• 30% fan speed at 40°C
• 40% at 50°C
• 50% at 60°C
• 70% at 70°C
• 100% at 80°C+

Options:

• --interval N - Check temperature every N seconds (default: 5)
• --single-use - Apply once and exit
• --retry - Retry on errors
• --retry-interval N - Retry wait time in seconds (default: 10)
• --default-speed N - Speed below first curve point (default: 30)
• --power-limit N - Also enforce power limit in watts

With power limit:

sudo nvctl control \
  --speed-pair 60:50 \
  --speed-pair 80:100 \
  --power-limit 280

Global Options

nvctl [OPTIONS] <COMMAND>

Options:
  -v, --verbose          Enable verbose output
      --format <FORMAT>  Output format [table|json|compact]
      --gpu <INDEX>      Target GPU by index (0-based)
      --gpu-name <NAME>  Target GPU by name (partial match)
      --gpu-uuid <UUID>  Target GPU by UUID
      --dry-run          Preview changes without applying
  -c, --config <FILE>    Path to config file
  -h, --help             Print help
  -V, --version          Print version

Configuration

Create ~/.config/nvctl/config.toml:

[general]
verbose = false
dry_run = false
interval = 5

[gpu]
index = 0

[fan]
default_speed = 30

[[fan.curve]]
temperature = 40
speed = 30

[[fan.curve]]
temperature = 60
speed = 50

[[fan.curve]]
temperature = 75
speed = 70

[[fan.curve]]
temperature = 85
speed = 100

[power]
limit_watts = 300

[thermal]
acoustic_limit = 83

[automation]
enabled = false
interval_seconds = 2
cooldown_seconds = 10
release_delay_seconds = 5
fallback_profile = "Quiet"

[[automation.rules]]
name = "games"
profile = "Performance"
processes = ["steam_app_*", "*game*"]
process_type = "graphics"
priority = 100
min_duration_seconds = 3

Use with:

nvctl --config ~/.config/nvctl/config.toml control

# Or set environment variable
export NVCTL_CONFIG=~/.config/nvctl/config.toml
nvctl control

Output Formats

Table (default)

nvctl info --power

JSON

nvctl info --power --format json

{
  "gpu_name": "NVIDIA GeForce RTX 4090",
  "gpu_index": 0,
  "current_usage_watts": 85,
  "limit_watts": 450,
  "min_limit_watts": 150,
  "max_limit_watts": 600,
  "default_limit_watts": 450
}

Commands that produce multiple records emit one JSON array, so stdout always contains one valid JSON document.

Compact

nvctl info --power --format compact

Permissions

Read operations and the alert daemon normally run as the current user. Depending on the driver and system policy, GPU mutation commands may require elevated privileges:

# Works without sudo
nvctl list
nvctl info
nvctl fan status
nvctl power status
nvctl health
nvctl processes
nvctl alerts list
nvctl alerts rules

# May require sudo
sudo nvctl fan policy manual
sudo nvctl fan speed 75
sudo nvctl power limit 250
sudo nvctl thermal limit 80

For non-root mutation access, use an administrator-defined, least-privilege device or service policy appropriate for your distribution. Avoid world-writable NVIDIA device nodes.

Troubleshooting

"NVML library not found"

Ensure NVIDIA drivers are installed:

# Check driver
nvidia-smi

# Library location
ldconfig -p | grep libnvidia-ml

# Arch Linux
sudo pacman -S nvidia-utils

# Ubuntu/Debian
sudo apt install nvidia-utils-xxx  # Replace with driver version

# Fedora
sudo dnf install nvidia-driver-libs

"Insufficient permissions"

Use sudo for the individual mutation command, or ask an administrator to configure a least-privilege policy (see Permissions).

"Fan control not available"

Some GPUs (especially mobile/laptop) don't support manual fan control via NVML. Check with nvctl info --fan.

"Fan speed won't change"

1. Set policy to manual first: sudo nvctl fan policy manual
2. Then set speed: sudo nvctl fan speed 75

"GPU not found"

# List available GPUs
nvctl list

# Check NVML directly
nvidia-smi -L

# Verify driver
lsmod | grep nvidia

Building

Uses a Makefile for all build and check operations:

# Build release binary (outputs to bin/)
make build

# Run all quality checks
make check

# Full CI pipeline (clean + checks + build)
make ci-full

# Show all available targets
make help

Individual Commands

make release    # Build optimized release binary
make debug      # Build debug binary
make test       # Run tests
make lint       # Run clippy
make fmt        # Format code
make clean      # Remove build artifacts
make doc        # Generate and open documentation
make install    # Install to /usr/local/bin (requires sudo)

Running

make run ARGS='list --format json'
make run-release ARGS='info --all'

Shell Completions

nvctl supports tab-completion for bash, zsh, and fish.

Generate and Install (Recommended)

# Generate completions for all shells
make completions

# Install system-wide (requires sudo)
sudo make install-completions

Manual Generation

# Generate for specific shell
nvctl completions bash > nvctl.bash
nvctl completions zsh > _nvctl
nvctl completions fish > nvctl.fish

Manual Installation

Bash:

# System-wide
sudo cp nvctl.bash /usr/share/bash-completion/completions/nvctl

# User only
mkdir -p ~/.local/share/bash-completion/completions
cp nvctl.bash ~/.local/share/bash-completion/completions/nvctl

Zsh:

# System-wide
sudo cp _nvctl /usr/share/zsh/site-functions/_nvctl

# User only (add to fpath in .zshrc)
mkdir -p ~/.zfunc
cp _nvctl ~/.zfunc/_nvctl
# Add to .zshrc: fpath=(~/.zfunc $fpath)

Fish:

# System-wide
sudo cp nvctl.fish /usr/share/fish/vendor_completions.d/nvctl.fish

# User only
cp nvctl.fish ~/.config/fish/completions/nvctl.fish

Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass: cargo test
5. Ensure no clippy warnings: cargo clippy -- -D warnings
6. Submit a pull request

Code Standards

• No .unwrap() or .expect() in library code - use Result
• All public items must have /// documentation
• Domain types validate input on construction
• Tests required for new functionality
• Follow existing patterns in the codebase

License

MIT License - see LICENSE for details.

Acknowledgments

• nvml-wrapper - Rust bindings for NVML
• clap - CLI argument parsing
• iced - Cross-platform GUI framework for the GUI application
• NVIDIA for the NVML library