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

Option 1: One-liner (recommended)

curl -fsSL https://gitea.zephyre.one/Pakobbix/nvcurve/raw/branch/main/install.sh | bash

The script checks prerequisites (installs uv if missing), clones the repository, and installs NVCurve. The React frontend is compiled automatically during the build by a hatchling build hook (hatch_build.py).

Option 2: From a clone

git clone https://gitea.zephyre.one/Pakobbix/nvcurve.git
cd nvcurve
./install.sh

Equivalent manual steps (what the script does):

git clone https://gitea.zephyre.one/Pakobbix/nvcurve.git
cd nvcurve
uv tool install .   # frontend is built automatically if missing/stale

Option 3: Direct from git (no clone, no script)

uv tool install "git+https://gitea.zephyre.one/Pakobbix/nvcurve.git"

To install a specific branch:

uv tool install "git+https://gitea.zephyre.one/Pakobbix/nvcurve.git@<branch>"

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
uv tool install --force .

The frontend is rebuilt automatically if it is missing or older than the frontend sources. If you modified frontend code locally, run make frontend first (or rm -rf frontend/dist).

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 the installed package contains the frontend. If frontend/dist is empty or missing, rebuild with make frontend (or cd frontend && npm ci && npm run build) and reinstall with uv tool install --force ..

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.