lhh666-6 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
| 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
- Never use
pip install— alwaysuv pip installoruv add - Never install globally — use
uv tool installfor CLI tools - Always work in a venv — created by
uv venvoruv sync - Use
uv run— to execute scripts within the project environment
This Project
The Task Management system uses uv:
cd "Task Management"
uv sync # Install dependencies
uv run python .scripts/tasks # Run CLI tools
On your 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/[your-project]/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.