# uv Setup — Per-Platform

This skill runs every data operation through `uv run --with ...`. If `uv --version` fails, set uv up with the automated scripts or the manual commands below, then verify.

## Automated (recommended)

| Platform | Command |
|---|---|
| macOS / Linux / WSL / Git Bash | `bash scripts/setup-uv.sh` |
| Windows (PowerShell) | `powershell -ExecutionPolicy Bypass -File scripts/setup-uv.ps1` |

Both scripts: detect OS + architecture → install uv to the latest release when missing → upgrade it when present (`uv self update`) → make it resolvable for the current shell → verify with `uv --version`. They are idempotent — safe to re-run any time.

## Manual install per platform

### macOS

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh        # official installer → ~/.local/bin/uv
# or, with Homebrew:
brew install uv
```

### Linux (x86_64 / aarch64)

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh        # official installer → ~/.local/bin/uv
```

The installer detects glibc vs musl and downloads the right static binary. On minimal containers, ensure `curl` (or `wget`) exists; `wget -qO- https://astral.sh/uv/install.sh | sh` is the fallback.

### Windows (native)

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# or, with winget:
winget install --id=astral-sh.uv -e
```

### Windows Subsystem for Linux / Git Bash

Use the Linux/macOS installer inside the Unix shell, not the PowerShell installer:

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

### CI

```yaml
# GitHub Actions
- uses: astral-sh/setup-uv@v5
# or plain shell anywhere:
- run: curl -LsSf https://astral.sh/uv/install.sh | sh
```

## PATH notes

- The official installers put the binary in `~/.local/bin` (Unix) or `%USERPROFILE%\.local\bin` (Windows). New shells get it automatically on most setups; an already-open shell needs `export PATH="$HOME/.local/bin:$PATH"` (Unix) or `$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"` (PowerShell) once.
- Homebrew and winget install into their own prefixes that are already on PATH.

## Upgrade to latest

```bash
uv self update
```

`uv self update` only works for official-installer binaries; Homebrew/winget installs upgrade through their package manager (`brew upgrade uv` / `winget upgrade astral-sh.uv`). The setup scripts handle this automatically.

## Verify

```bash
uv --version
```

## Offline / air-gapped

Download the matching archive from the uv GitHub releases page, extract it, and put the `uv` binary anywhere on PATH. `uv run --with <pkg>` still needs network for first-time package resolution unless a mirror is configured via `UV_INDEX_URL`.