Skip to content

README_UV.md

Latest commit

 

History

History
162 lines (114 loc) · 3.1 KB

README_UV.md

File metadata and controls

162 lines (114 loc) · 3.1 KB

UV Setup Guide

This project uses uv for fast, reliable Python package management.

Why uv?

  • ⚡ 10-100x faster than pip
  • 🔒 Deterministic dependency resolution
  • 🎯 Automatic virtual environment management
  • 📦 Modern tooling built for Python 3.10+

Quick Setup

1. Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Setup Project

# Clone repository
git clone <repo-url>
cd ab

# One command setup (creates venv + installs dependencies)
uv sync

# Or use the setup script
./scripts/setup_uv.sh  # macOS/Linux
# or
.\scripts\setup_uv.ps1  # Windows

3. Activate Virtual Environment (Optional)

# uv run works without activation, but for interactive use:
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

Common Workflows

Development

# Install dependencies
uv sync

# Run tests
uv run pytest tests/

# Run scripts
uv run python scripts/quick_start.py

# Or activate venv for interactive use
source .venv/bin/activate
pytest tests/

Adding Dependencies

# Add to pyproject.toml, then:
uv sync

# Or install directly
uv pip install package-name

Updating Dependencies

# Update lock file
uv lock

# Sync with updated dependencies
uv sync

Virtual Environment

uv automatically creates .venv/ in the project root:

  • ✅ Created automatically with uv sync
  • ✅ No manual setup needed
  • ✅ Can be activated manually
  • ✅ Gitignored (already in .gitignore)

Commands Reference

Task Command
Setup project uv sync
Run command uv run <command>
Install package uv pip install <package>
Update lock uv lock
List Python versions uv python list
Install Python uv python install 3.10

Migration from pip

If you're used to pip, here's the mapping:

pip uv
pip install -e ".[dev]" uv sync
pip install package uv pip install package
python script.py uv run python script.py
pytest tests/ uv run pytest tests/

Best Practices

  1. ✅ Use uv sync for initial setup and dependency updates
  2. ✅ Use uv run for one-off commands (no activation needed)
  3. ✅ Activate venv for interactive development sessions
  4. ✅ Commit uv.lock for reproducible builds (when generated)
  5. ✅ Use .python-version to specify Python version

Troubleshooting

uv not found

# Add to PATH
export PATH="$HOME/.cargo/bin:$PATH"

# Or restart terminal after installation

Virtual environment issues

# Delete and recreate
rm -rf .venv
uv sync

Lock file

# Generate lock file
uv lock

# Note: uv.lock is optional but recommended for reproducibility

More Information