python-env

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

| Task | Command | |------|---------| | Create venv | uv venv | | Install package | uv pip install <package> | | Install from requirements | uv pip install -r requirements.txt | | Run script in project | uv run python script.py | | Run with dependencies | uv run --with pandas python script.py | | Install CLI tool globally | uv tool install <tool> | | Sync project deps | uv sync | | Add dependency | uv add <package> |

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

Avon 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,benchmark-gaming-llm-safety}/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 Avon — the module system assumes conda.