nvcurve/docs/Installation.md

Installation

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

Prerequisites

Make sure your system has the following before proceeding:

• Linux (any distribution)
• NVIDIA GPU with proprietary drivers installed
• Python 3.12+
• Node.js 18+ and pnpm (for frontend development)
• Root/sudo access (required for hardware interactions)

Quick Install (Pre-built)

The recommended way to install NVCurve for end-use is via uv:

uv tool install nvcurve

This installs the CLI tool with the pre-built frontend bundled inside. After installation, verify everything works:

nvcurve setup

Installation from Source

Building from source is necessary if you want to modify the frontend, contribute to the project, or run a development build.

Step 1: Clone the Repository

git clone https://github.com/your-username/nvcurve.git
cd nvcurve

Step 2: Set Up the Python Environment

Create a virtual environment and install the Python dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Or if you use uv:

uv venv
source .venv/bin/activate
uv pip install -e .

Step 3: Build the Frontend

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

Navigate to the frontend directory and install its dependencies:

cd frontend
pnpm install

Build the production bundle:

pnpm run build

This produces a dist/ directory containing the compiled static assets. The hatch build system automatically includes frontend/dist in the Python package under nvcurve/frontend/dist.

Step 4: Reinstall the Python Package

After building the frontend, reinstall the Python package so it picks up the new frontend assets:

cd ..
pip install -e .

Step 5: Verify the Installation

Run the hardware compatibility check:

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
pnpm run dev

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

# In another terminal
nvcurve serve start

Upgrading

Pre-built Install

uv tool upgrade nvcurve

If you're running NVCurve as a systemd service, restart it after upgrading:

nvcurve service restart

Source Install

git pull
pip install -e .
cd frontend && pnpm install && pnpm run build
cd .. && pip install -e .

Troubleshooting

nvcurve command not found

Ensure your virtual environment is activated, or that the package installation directory is on your PATH.

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 pnpm run build and reinstall the Python package.

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.