nvcurve/docs/Installation.md

Installation

This guide covers installing NVCurve from source, including building the frontend.

Important

Blackwell GPU Fork — This repository contains Blackwell-specific features (extended memory offset > +1000 MHz, fan curve control). The pre-built PyPI package does NOT include these. You must build from source.

Prerequisites

• Linux with NVIDIA proprietary drivers
• Python 3.12+
• Node.js 18+ and npm
• uv — Python package manager
• Root/sudo access (required for GPU hardware interactions)

Installing uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Or via your package manager:

# Arch Linux
sudo pacman -S uv

# Debian/Ubuntu
pip install uv

Installation from Source

Step 1: Clone the Repository

git clone <this-repo-url>.git
cd nvcurve

Step 2: Build the Frontend

The frontend is a React + TypeScript + Vite application in the frontend/ directory.

cd frontend
npm install
npm run build
cd ..

This produces a dist/ directory with the compiled static assets. The hatch build system bundles frontend/dist into the Python package.

Step 3: Install the Python Package

uv tool install .

This installs nvcurve as a system-wide tool with the bundled frontend.

Step 4: Verify

nvcurve setup

This performs four checks:

1. NvAPI function probe — verifies all required functions resolve in your driver
2. Curve read — reads and displays your current V/F curve as a baseline
3. Write-verify — writes +5 MHz to a safe point, reads it back, and confirms the change
4. Restore — automatically restores the state from before the test write

If setup reports Compatible, you're ready to go.

Frontend Development Mode

For active frontend development, run the Vite dev server instead of building:

cd frontend
npm run dev

This starts a hot-reload development server. The backend server runs separately:

# In another terminal
nvcurve serve start

Upgrading

cd nvcurve
git pull
cd frontend && npm run build && cd ..
uv tool install .

If running as a systemd service:

nvcurve service restart

Troubleshooting

nvcurve command not found

Ensure uv tools directory is on your PATH. After installing uv, log out and back in, or run:

source ~/.local/bin/env  # or wherever uv installed

Frontend not loading in the web UI

Verify that frontend/dist exists and contains built assets. If the directory is empty or missing, rebuild with npm run build and reinstall with uv tool install ..

NvAPI functions not found

Your NVIDIA driver may not expose the required undocumented functions. Try updating to the latest driver version. Run nvcurve read --diag for detailed diagnostics.

Permission denied on hardware operations

All hardware-interacting commands require root. The CLI will automatically escalate via sudo when needed. If sudo is not configured for your user, run commands with sudo explicitly.

Blackwell memory offset limited to +1000 MHz

The standard NVCurve on PyPI caps memory offset at +1000 MHz. This fork raises the cap to +3000 MHz for Blackwell GPUs. If you installed from PyPI, uninstall and rebuild from source.