# 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](https://docs.astral.sh/uv/)** — Python package manager
- **Root/sudo access** (required for GPU hardware interactions)

### Installing uv

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

Or via your package manager:

```bash
# Arch Linux
sudo pacman -S uv

# Debian/Ubuntu
pip install uv
```

## Installation from Source

### Step 1: Clone the Repository

```bash
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.

```bash
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

```bash
uv tool install .
```

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

### Step 4: Verify

```bash
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:

```bash
cd frontend
npm run dev
```

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

```bash
# In another terminal
nvcurve serve start
```

## Upgrading

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

If running as a systemd service:

```bash
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:

```bash
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.