Use when setting up Python projects, installing packages, running Python scripts, or managing dependencies - enforces UV package manager workflow with automatic virtual environment handling, replacing pip and manual venv management
All Python work on this system uses the uv package manager exclusively. UV handles virtual environments automatically - no manual activation, no pip, no confusion.
Core principle: UV replaces both pip and manual venv management. One tool, zero friction.
Use this workflow when:
Do NOT use for:
| Task | Command |
|---|
| Notes |
|---|
| Initialize project | uv init --bare && uv venv --seed --prompt " 🌞 " | Sets up bare project with seeded venv |
| Add dependency | uv add <package> && uv sync | Always sync after adding |
| Remove dependency | uv remove <package> && uv sync | Always sync after removing |
| Run Python script | uv run python script.py | No venv activation needed |
| Run any command | uv run <command> | Runs in project's venv context |
| Install all deps | uv sync | Syncs pyproject.toml to venv |
| Update dependencies | uv lock --upgrade | Updates lock file |
uv for ALL Python operationsuv run prefixuv add pkg && uv syncpip or pip3 (blocked in permissions)python or python3 directly (blocked in permissions)source venv/bin/activate)virtualenv or venv commands| Mistake | Why It's Wrong | Correct Approach |
|---|---|---|
pip install requests | Uses pip instead of uv | uv add requests && uv sync |
python script.py | Bypasses UV's venv handling | uv run python script.py |
uv add pandas (without sync) | Dependencies not installed | uv add pandas && uv sync |
source .venv/bin/activate | Manual venv management unnecessary | Just use uv run |
| Running from wrong directory | UV can't find pyproject.toml | cd to project root first |
UV requires you to be in the correct project directory because it looks for pyproject.toml:
# ❌ Wrong - not in project directory
cd ~
uv run python my_project/script.py # Won't find pyproject.toml
# ✅ Correct - in project directory
cd ~/my_project
uv run python script.py # Finds pyproject.toml
# Navigate to projects directory
cd ~/projects/my-new-project
# Initialize with bare template and seeded venv
uv init --bare && uv venv --seed --prompt " 🌞 "
# Add dependencies
uv add pandas numpy && uv sync
# Create and run script
uv run python analyze.py
# Navigate to project
cd ~/projects/my-project
# Add package and sync in one command
uv add requests && uv sync
# Verify it works
uv run python -c "import requests; print(requests.__version__)"
# Simple script execution
uv run python main.py
# Script with arguments
uv run python process.py --input data.csv --output results.json
# Interactive Python shell with project dependencies
uv run python
If you catch yourself about to:
pip installpython directlySTOP. Use UV commands instead.
uv run handles venv automatically"Command not found: uv"
brew install uv"No pyproject.toml found"
cd to project root or initialize with uv init --bare."Package not found after uv add"
uv add package && uv sync"Wrong Python version"
uv python pin 3.11