# 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

### Option 1: One-liner (recommended)

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

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

Equivalent manual steps (what the script does):

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

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

To install a specific branch:

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

### 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
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:

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