Python Environment Management

CRITICAL RULE: Never use pip directly. Always use uv. This applies to all Python package management.

Golden Rule

ALWAYS use uv for Python package and environment management. Never use pip directly.

Commands

Project Setup

For new projects:

uv init
uv add <dependencies>
uv sync

For existing projects with pyproject.toml:

uv sync
uv run python main.py

Rules

1. Never use pip install — always uv pip install or uv add
2. Never install globally — use uv tool install for CLI tools
3. Always work in a venv — created by uv venv or uv sync
4. Use uv run — to execute scripts within the project environment

Typical Project

For a project with a Python entry point:

cd <project>
uv sync                           # Install dependencies
uv run python scripts/task.py     # Run a project script

On [HPC cluster] HPC

[HPC cluster] uses Miniconda3 + Lmod (not uv) because cluster users need to compose with module load CUDA/12.6.0 and other pre-built modules. The project-specific pattern is hpc/env-setup.sh (conda create + pip install) — see docs/guides/hpc.md and reference implementations under Projects/NLP/{example-project-a,example-project-b}/hpc/env-setup.sh. The local dev env still uses uv; HPC gets its own conda env with identical pins. Don't try to port uv to [HPC cluster] — the module system assumes conda.