ARIA
a8462e696c
- hatch_build.py: custom hatchling build hook that compiles the React frontend (npm ci + build) when frontend/dist is missing or stale, so 'uv tool install git+https://gitea.zephyre.one/Pakobbix/nvcurve.git' works as a single command - install.sh: curl|bash installer (checks prerequisites, auto-installs uv, clones and installs) - Makefile: dev targets (frontend, install, dev, test, clean) - README/docs: document the one-liner, clone, and direct-git installs
141 lines
3.8 KiB
Markdown
141 lines
3.8 KiB
Markdown
# 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.
|