UV Quick Reference
Installation
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Add to PATH (add to ~/.bashrc for persistence)
export PATH="$HOME/.local/bin:$PATH"
Essential Commands
Initial Setup
# Clone the repo and navigate to it
cd mlops-with-mlflow
# Sync all dependencies (creates .venv and installs everything)
uv sync
Daily Development
# Activate the virtual environment (optional, most commands work without it)
source .venv/bin/activate
# Build all packages
make build
# Run all tests
make test
# Clean build artifacts
make clean
Dependency Management
# Add a dependency to root project
uv add package-name
# Add a dev dependency
uv add --dev pytest-mock
# Add dependency to specific package
cd src/doe-library
uv add scipy
# Update all dependencies
uv sync --upgrade
# Update specific package
uv add package-name@latest
Running Scripts
# Run a Python script (ensures correct environment)
uv run python script.py
# Run pytest
uv run pytest
# Run with specific package
cd src/doe-library
uv run pytest tests/
Package Building
# Build a specific package
cd src/doe-library
uv build
# Install package in editable mode
uv pip install -e .
Common Workflows
Adding a New Package to Workspace
- Create package directory in
src/ - Create
pyproject.toml:[project]
name = "package_name"
version = "0.1.0"
requires-python = ">=3.13"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
- Add to workspace in root
pyproject.toml:[tool.uv.workspace]
members = [
"src/package_name",
# ... other packages
]
- Run
uv sync
Updating Python Version
# List available Python versions
uv python list
# Install specific version
uv python install 3.13
# Pin project to version
uv python pin 3.13
Debugging
# Check what Python is being used
uv python --version
# Check installed packages
uv pip list
# Verify package installation
uv pip show package-name
# Clean cache if having issues
uv cache clean
File Structure
mlops-with-mlflow/
├── .python-version # Python version (3.13)
├── pyproject.toml # Root workspace config
├── uv.lock # Locked dependencies
├── .venv/ # Virtual environment (auto-generated)
├── build.sh # Build script (uses uv)
├── test.sh # Test script (uses uv)
└── src/
├── doe-library/ # Package 1
├── io-library/ # Package 2
└── ...
Environment Variables
# Prefer copying over hardlinking (useful for cross-filesystem scenarios)
export UV_LINK_MODE=copy
# Use specific Python version
export UV_PYTHON=3.13
# Custom cache location
export UV_CACHE_DIR=/path/to/cache
Troubleshooting
| Problem | Solution |
|---|
uv: command not found | Add $HOME/.local/bin to PATH |
| Python 3.13 not found | Run uv python install 3.13 |
| Sync fails | Try uv cache clean && uv sync |
| Package not found | Check it’s in workspace members |
| Build fails | Ensure requires-python = ">=3.13" |
vs pip/venv
| Task | pip/venv | uv |
|---|
| Create venv | python -m venv .venv | uv sync |
| Activate | source .venv/bin/activate | Not needed for uv run |
| Install deps | pip install -r requirements.txt | uv sync |
| Add package | pip install package | uv add package |
| Run script | python script.py | uv run python script.py |
| Lock deps | pip freeze > requirements.txt | uv lock (automatic) |
Tips
- No activation needed:
uv run automatically uses the right environment - Lock file:
uv.lock is auto-generated, commit it for reproducibility - Workspace: All packages share the same environment, faster installs
- Speed: ~50x faster than pip for most operations
- Standards: Uses PEP 621 and modern packaging standards
Links