Dependency Management

Manage Python dependencies with uv following workspace conventions.

Trigger

Use this skill when the user asks to:

• •Add or remove a dependency
• •Update dependencies
• •Sync or install dependencies
• •Fix dependency issues

Quick Reference

Procedure: Adding Dependencies

Runtime Dependencies

1. •

   Add to workspace root:

   bash

   uv add <package_name>
   

2. •

   If needed by specific project, also add to project's pyproject.toml:

   toml

   [project]
   dependencies = [
       "new-package>=X.Y.Z",  # Must match workspace root version
   ]
   

Development Dependencies

Add to appropriate group in workspace root only:

# Linters, formatters, type checkers
uv add <package_name> --group dev

# Test frameworks and helpers
uv add <package_name> --group test

# CI/CD and deployment tools
uv add <package_name> --group release

Decision Tree

Is it needed at runtime in production?
├── YES → uv add <package> (runtime dependency)
└── NO → Continue...

Is it for running tests?
├── YES → uv add <package> --group test
└── NO → Continue...

Is it for deploying/releasing?
├── YES → uv add <package> --group release
└── NO → uv add <package> --group dev

Procedure: Removing Dependencies

# Remove from workspace root
uv remove <package_name>

# Remove from specific project
cd projects/<project> && uv remove <package_name>

# Remove from group
uv remove <package_name> --group dev

Procedure: Updating Dependencies

Update All

uv lock --upgrade
uv sync

Update Specific Package

uv lock --upgrade-package <package_name>
uv sync

Post-Update Checklist

1. •Check resolved versions in uv.lock
2. •Update pyproject.toml constraints to match (recommended)
3. •Run tests
4. •Commit both pyproject.toml and uv.lock together

Critical Rules

Subset Rule

Project dependencies MUST be a subset of workspace root:

Workspace root: [A, B, C, D]
Project 1:      [A, B]      ✅ Valid subset
Project 2:      [B, C, D]   ✅ Valid subset
Project 3:      [A, E]      ❌ E not in workspace root!

If project needs new dependency → add to workspace root FIRST.

Version Constraints

Always use >= with tested version:

# Good
"google-cloud-bigquery>=3.30.0"

# Bad
"google-cloud-bigquery"        # No version
"google-cloud-bigquery>3.0"    # Untested minimum

Lock File Rules

• •Always commit uv.lock
• •Use --frozen in CI/CD
• •Never manually edit uv.lock

Standard Dependency Groups

Troubleshooting

See troubleshooting.md for common issues.