File size: 9,202 Bytes
3cd1076 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 | # UV Setup Guide
This guide covers installing uv, configuring shell helpers, and using the companion functions to quickly set up a Python development environment.
## 1. Installing uv
Use the official installer with `UV_INSTALL_DIR` to set a custom path:
```sh
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="$HOME/opt/uv" sh
```
`$HOME/opt/uv` is used as the example path; replace it with any directory you prefer.
| Artifact | Path |
|----------|------|
| uv binary | `$HOME/opt/uv/uv` |
| Env script | `$HOME/opt/uv/env` |
| Tip | Hand this doc to Claude Code or another AI coding assistant — they can run through the steps directly |
|-----|------------------------------------------------------------------------------------------------------|
## 2. Shell Configuration
Add the following to your `.zshrc` or `.bashrc` (adjust paths as needed).
### 2.1 Paths & Environment
```sh
# Load uv environment variables
. "$HOME/opt/uv/env"
# Ensure local bin and uv are on PATH
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/opt/uv:$PATH"
# Enable shell completion (zsh)
eval "$(uv generate-shell-completion zsh)"
```
| Config | Purpose |
|--------|---------|
| `. "$HOME/opt/uv/env"` | Sources the env script generated at install time, adding uv's bin to PATH |
| `generate-shell-completion` | Generates zsh/bash tab-completion — type `uv ` then press Tab to see subcommands |
### 2.2 Global Defaults
```sh
# uv package cache (keep it off $HOME to save space)
export UV_CACHE_DIR="$HOME/data/.cache/uv"
# Default Python interpreter for creating venvs
export UV_PYTHON="$HOME/data/.cache/micromamba/envs/syspy/bin/python"
# Default PyPI index
export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple"
```
| Config | Purpose | Recommendation |
|--------|---------|----------------|
| `UV_CACHE_DIR` | Where uv stores downloaded wheel caches | Point to a large partition to avoid filling `$HOME` |
| `UV_PYTHON` | Base Python used by `uv sync` / `uv venv` | Use a reliable system Python managed by micromamba or conda |
| `UV_DEFAULT_INDEX` | Default PyPI index for `uv pip install` / `uv sync` | Aliyun mirror is recommended for users in China |
| About `UV_PYTHON` | uv needs a base Python interpreter to create `.venv`. The `syspy` here is a CPython installed via micromamba, isolated from the system Python |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------|
---
## 3. Shell Helper Functions
These functions provide shortcuts for switching mirrors, managing Python versions, and activating/creating environments.
### 3.1 `uv-index-set` — Switch PyPI Mirror
```sh
uv-index-set() {
case "$1" in
aliyun)
export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple"
echo "✅ Switched to Aliyun mirror"
;;
tuna)
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"
echo "✅ Switched to TUNA mirror"
;;
pypi)
export UV_DEFAULT_INDEX="https://pypi.org/simple"
echo "✅ Switched to PyPI official"
;;
*)
echo "❌ Unknown index: '$1'. Options: aliyun, tuna, pypi" >&2
return 1
;;
esac
}
```
| Command | Effect |
|---------|--------|
| `uv-index-set aliyun` | Switch to Aliyun mirror (recommended in China) |
| `uv-index-set tuna` | Switch to Tsinghua TUNA mirror |
| `uv-index-set pypi` | Switch to PyPI official |
| Property | Detail |
|----------|--------|
| Scope | Current shell session only; not persisted across terminals |
| Mechanism | Modifies the `UV_DEFAULT_INDEX` env var; all subsequent `uv sync` / `uv pip install` use the specified index |
| Note | This project already pins indices via `[[tool.uv.index]]` in `pyproject.toml` (Aliyun default + PyTorch-specific), so dependency resolution points to Aliyun even without this function |
|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
---
### 3.2 `uv-set-system-python` — Restore System Python
```sh
uv-set-system-python() {
export UV_PYTHON="$HOME/data/.cache/micromamba/envs/syspy/bin/python"
echo "✅ UV_PYTHON restored to system syspy"
}
```
| Property | Detail |
|----------|--------|
| When to use | After `uvon` has pointed `UV_PYTHON` to a `.venv`; call this before creating a new venv |
| Typical usage | `uv-set-system-python` then `uv sync` will use syspy as the base |
---
### 3.3 `uv-set-default-python` — Point UV_PYTHON to Current venv
```sh
uv-set-default-python() {
export UV_PYTHON="$(pwd)/.venv/bin/python"
echo "✅ UV_PYTHON set to $(pwd)/.venv/bin/python"
}
```
| Property | Detail |
|----------|--------|
| Called by | `uvon` invokes this automatically; no need to run it manually |
| Purpose | Keeps `UV_PYTHON` in sync with the active venv so subsequent `uv` commands use the same interpreter |
---
### 3.4 `uv-unset-python` — Clear UV_PYTHON
```sh
uv-unset-python() {
unset UV_PYTHON
echo "✅ UV_PYTHON cleared"
}
```
| Property | Detail |
|----------|--------|
| When to use | When you want uv to auto-discover Python from PATH rather than using a preset |
| Typical scenario | The first step inside `uv-create-venv` |
---
### 3.5 `uvon` — Activate the Project venv
```sh
uvon() {
if [ -f .venv/bin/activate ]; then
source .venv/bin/activate
echo "✅ uv venv activated"
uv-set-default-python
else
echo ".venv/bin/activate not found"
return 1
fi
}
```
| Note | This is the most frequently used command — just `cd` into a project and run `uvon` |
|------|-------------------------------------------------------------------------------------|
| Step | Action | Effect |
|------|--------|--------|
| 1 | `source .venv/bin/activate` | Activates the venv; `python` and `pip` now point to `.venv` |
| 2 | `uv-set-default-python` | Points `UV_PYTHON` to the active venv for future uv operations |
| Scenario | Command |
|----------|---------|
| Start daily work | `cd <project-dir> && uvon` |
| Run scripts afterwards | `python ...` |
| Note | `uvon` only activates an existing `.venv` — it does not install anything. If the venv doesn't exist yet, use `uv-create-venv` first |
|------|-------------------------------------------------------------------------------------------------------------------------------------|
---
### 3.6 `uv-create-venv` — Create & Activate a New venv
```sh
uv-create-venv() {
uv-unset-python
uv sync
echo "✅ uv venv created"
uvon
}
```
| Note | This is the complete command for setting up a fresh environment |
|------|-----------------------------------------------------------------|
| Step | Action | Effect |
|------|--------|--------|
| 1 | `uv-unset-python` | Clears `UV_PYTHON` so uv uses the system default Python |
| 2 | `uv sync` | Reads `pyproject.toml` + `uv.lock`, creates `.venv`, and installs all dependencies |
| 3 | `uvon` | Activates the newly created venv and configures the environment |
| Scenario | Command |
|----------|---------|
| After first clone | `git clone ... && cd <project-dir> && uv-create-venv` |
| Rebuild after lockfile update | `rm -rf .venv && uv-create-venv` |
| vs. bare `uv sync` | `uv-create-venv` runs `uv-unset-python` first to ensure the system Python is used, avoiding nested references from an already-active venv. If you understand this nuance, `uv sync && uvon` is equivalent |
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
---
## 4. Typical Workflows
### 4.1 First-Time Project Setup
```sh
# 1. Clone the project
git clone --recurse-submodules <repo-url>
cd <project-dir>
# 2. Initial sync
uv-create-venv
```
### 4.2 Daily Development
```sh
cd <project-dir>
uvon # Activate the environment
python ... # Run scripts or training
```
### 4.3 Switching Mirrors
```sh
uv-index-set pypi # Temporarily use the official index (e.g. to check package versions)
uv pip install <pkg>
uv-index-set aliyun # Switch back
```
### 4.4 Adding Dependencies
```sh
uv add <package> # Production dependency
uv add --dev <package> # Dev dependency
uv add --extra gpu <pkg> # GPU-extra dependency
```
---
## 5. Configuration Hierarchy
| Layer | Key Contents | Scope | Priority | Description |
|-------|-------------|-------|----------|-------------|
| Env vars (shell rc) | `UV_CACHE_DIR`, `UV_PYTHON`, `UV_DEFAULT_INDEX` | All projects | Low (overridable) | Global default behavior |
| `pyproject.toml` | `[tool.uv]` block | Current project | Medium (overrides env vars) | Project-level: indices, sources, build isolation, etc. |
| `uv.lock` | Exact pinned dependency tree | Current project | High (final authority) | Auto-maintained by `uv sync`; guarantees identical dependencies for all developers |
|