dependency-management

Automatically applies when managing Python dependencies. Ensures proper use of uv/Poetry, lock files, version constraints, conflict resolution, and dependency security.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates and standardizes Python dependency management by implementing modern best practices with tools like uv and Poetry. It ensures project reproducibility through rigorous lock file management, handles complex version constraints to prevent dependency conflicts, and integrates security auditing to protect the software supply chain from vulnerabilities.

Use Cases

  • Project Initialization: Setting up new Python projects with optimized pyproject.toml configurations using modern, high-performance tools like uv or Poetry.
  • Conflict Resolution: Identifying and resolving complex version mismatches and 'dependency hell' by applying correct versioning logic and overlapping constraints.
  • Security & Compliance: Implementing automated security scanning (pip-audit/safety) and vulnerability checks within the development workflow and CI/CD pipelines.
  • CI/CD Optimization: Configuring GitHub Actions and Dependabot to automate dependency updates, lock file synchronization, and environment reproducibility across different stages.
  • Legacy Migration: Converting legacy requirements.txt setups into modern, manageable formats to improve build speed and environment stability.
namedependency-management
descriptionAutomatically applies when managing Python dependencies. Ensures proper use of uv/Poetry, lock files, version constraints, conflict resolution, and dependency security.
categorypython

Dependency Management Patterns

When managing Python dependencies, follow these patterns for reproducible, secure environments.

Trigger Keywords: dependencies, uv, poetry, pip, requirements, lock file, dependency conflict, version pinning, pyproject.toml, pip-compile

Agent Integration: Used by backend-architect, devops-engineer, python-engineer

✅ Correct Pattern: Using uv

# Install uv (modern, fast dependency manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Initialize project
uv init myproject
cd myproject

# Add dependencies
uv add fastapi pydantic sqlalchemy

# Add dev dependencies
uv add --dev pytest pytest-cov black ruff mypy

# Add optional dependencies
uv add --optional docs sphinx

# Install all dependencies
uv sync

# Install with optional dependencies
uv sync --extra docs

# Update dependencies
uv lock --upgrade
uv sync

# Remove dependency
uv remove package-name

pyproject.toml with uv

# pyproject.toml
[project]
name = "myproject"
version = "0.1.0"
description = "My Python project"
requires-python = ">=3.11"

dependencies = [
    "fastapi>=0.109.0,<1.0.0",
    "pydantic>=2.5.0,<3.0.0",
    "sqlalchemy>=2.0.0,<3.0.0",
    "httpx>=0.26.0,<1.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "pytest-asyncio>=0.23.0",
    "black>=24.0.0",
    "ruff>=0.1.0",
    "mypy>=1.8.0",
]
docs = [
    "sphinx>=7.2.0",
    "sphinx-rtd-theme>=2.0.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.4.0",
    "black>=24.0.0",
]

# Lock file is automatically managed
# uv.lock contains exact versions

Using Poetry

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Initialize project
poetry new myproject
cd myproject

# Add dependencies
poetry add fastapi pydantic sqlalchemy

# Add dev dependencies
poetry add --group dev pytest pytest-cov black ruff mypy

# Add optional dependencies
poetry add --optional sphinx
poetry add --optional sphinx-rtd-theme

# Install dependencies
poetry install

# Install with optional dependencies
poetry install --extras docs

# Update dependencies
poetry update

# Lock dependencies without installing
poetry lock --no-update

# Remove dependency
poetry remove package-name

# Show dependency tree
poetry show --tree

pyproject.toml with Poetry

# pyproject.toml
[tool.poetry]
name = "myproject"
version = "0.1.0"
description = "My Python project"
authors = ["Your Name <you@example.com>"]
readme = "README.md"
packages = [{include = "myproject", from = "src"}]

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.109.0"
pydantic = "^2.5.0"
sqlalchemy = "^2.0.0"
httpx = "^0.26.0"

# Optional dependencies
sphinx = {version = "^7.2.0", optional = true}
sphinx-rtd-theme = {version = "^2.0.0", optional = true}

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
pytest-cov = "^4.1.0"
pytest-asyncio = "^0.23.0"
black = "^24.0.0"
ruff = "^0.1.0"
mypy = "^1.8.0"

[tool.poetry.extras]
docs = ["sphinx", "sphinx-rtd-theme"]

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Version Constraints

# Caret requirements (^) - recommended for libraries
# ^1.2.3 means >=1.2.3,<2.0.0
fastapi = "^0.109.0"

# Tilde requirements (~) - for bug fix updates
# ~1.2.3 means >=1.2.3,<1.3.0
pytest = "~7.4.0"

# Exact version (=)
black = "24.1.0"

# Greater than or equal
httpx = ">=0.26.0"

# Compatible release (~=)
# ~=1.2.3 is equivalent to >=1.2.3,<1.3.0
sqlalchemy = "~=2.0.0"

# Multiple constraints
pydantic = ">=2.5.0,<3.0.0"

# Wildcard
requests = "2.*"

Lock Files

# uv.lock (generated by uv)
# Contains exact versions of all dependencies
# Commit to version control for reproducibility

# poetry.lock (generated by poetry)
# Contains exact versions and hashes
# Commit to version control

# Benefits of lock files:
# 1. Reproducible builds
# 2. Security (verify hashes)
# 3. Faster installs
# 4. Conflict detection

Dependency Conflict Resolution

# Check for conflicts
# uv
uv lock

# Poetry
poetry lock

# If conflicts occur:
# 1. Check dependency requirements
poetry show package-name

# 2. Update conflicting package
poetry update package-name

# 3. Use version ranges that overlap
[tool.poetry.dependencies]
fastapi = "^0.109.0"  # Requires pydantic ^2.0
pydantic = "^2.5.0"   # Compatible!

# 4. Override dependencies if needed (Poetry)
[tool.poetry.overrides]
"problematic-package" = "1.2.3"

Security Scanning

# Check for security vulnerabilities with uv
uv pip list --outdated

# Use pip-audit for security scanning
pip install pip-audit
pip-audit

# Use safety
pip install safety
safety check

# Use Poetry's built-in audit (if available)
poetry audit

# GitHub Dependabot
# Automatically creates PRs for security updates
# Enable in .github/dependabot.yml

Dependabot Configuration

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
    reviewers:
      - "username"
    labels:
      - "dependencies"
      - "automated"

    # Group updates
    groups:
      development-dependencies:
        patterns:
          - "pytest*"
          - "black"
          - "ruff"
          - "mypy"

      production-dependencies:
        patterns:
          - "fastapi"
          - "pydantic"
          - "sqlalchemy"

    # Version updates
    versioning-strategy: increase

CI/CD Integration

# .github/workflows/dependencies.yml
name: Dependency Check

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: "0 0 * * 0"  # Weekly

jobs:
  check-dependencies:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Install dependencies
        run: uv sync

      - name: Check for outdated packages
        run: uv pip list --outdated

      - name: Security audit
        run: |
          pip install pip-audit
          pip-audit

      - name: Check lock file
        run: |
          uv lock
          git diff --exit-code uv.lock

Virtual Environment Management

# uv automatically manages virtual environments
uv venv  # Create virtual environment
source .venv/bin/activate  # Activate

# Poetry
poetry shell  # Activate Poetry environment
poetry env info  # Show environment info
poetry env list  # List environments
poetry env remove python3.11  # Remove environment

# Manual venv
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

Exporting Dependencies

# Export to requirements.txt format

# uv
uv pip compile pyproject.toml -o requirements.txt

# Poetry
poetry export -f requirements.txt --output requirements.txt
poetry export -f requirements.txt --with dev --output requirements-dev.txt
poetry export -f requirements.txt --extras docs --output requirements-docs.txt

# For Docker
poetry export -f requirements.txt --without-hashes --output requirements.txt

Docker Integration

# Dockerfile with uv
FROM python:3.11-slim

WORKDIR /app

# Install uv
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.cargo/bin:$PATH"

# Copy dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies
RUN uv sync --frozen --no-dev

# Copy application
COPY . .

CMD ["python", "-m", "myproject"]


# Dockerfile with Poetry
FROM python:3.11-slim

WORKDIR /app

# Install Poetry
RUN pip install poetry==1.7.1

# Configure Poetry
ENV POETRY_NO_INTERACTION=1 \
    POETRY_VIRTUALENVS_IN_PROJECT=1 \
    POETRY_VIRTUALENVS_CREATE=1 \
    POETRY_CACHE_DIR=/tmp/poetry_cache

# Copy dependency files
COPY pyproject.toml poetry.lock ./

# Install dependencies
RUN poetry install --without dev --no-root && rm -rf $POETRY_CACHE_DIR

# Copy application
COPY . .

# Install project
RUN poetry install --without dev

CMD ["poetry", "run", "python", "-m", "myproject"]

❌ Anti-Patterns

# ❌ No lock file
# Just pyproject.toml, no uv.lock or poetry.lock
# Non-reproducible builds!

# ✅ Better: Commit lock file
git add uv.lock  # or poetry.lock


# ❌ Unpinned versions in production
dependencies = ["fastapi"]  # Any version!

# ✅ Better: Use version constraints
dependencies = ["fastapi>=0.109.0,<1.0.0"]


# ❌ Using pip freeze without pip-tools
pip freeze > requirements.txt  # Includes transitive deps!

# ✅ Better: Use uv or poetry for dependency management


# ❌ Committing virtual environment
git add .venv/  # Huge, not portable!

# ✅ Better: Add to .gitignore
.venv/
venv/
*.pyc


# ❌ Not separating dev dependencies
dependencies = ["fastapi", "pytest", "black"]  # All mixed!

# ✅ Better: Use dev dependencies
[project]
dependencies = ["fastapi"]

[project.optional-dependencies]
dev = ["pytest", "black"]


# ❌ Ignoring security warnings
# pip install shows vulnerabilities but not addressed

# ✅ Better: Regular security audits
pip-audit
poetry audit

Best Practices Checklist

  • ✅ Use uv or Poetry for dependency management
  • ✅ Commit lock files (uv.lock, poetry.lock)
  • ✅ Use version constraints, not exact pins
  • ✅ Separate dev dependencies from production
  • ✅ Run security audits regularly
  • ✅ Use Dependabot for automatic updates
  • ✅ Don't commit virtual environments
  • ✅ Export requirements.txt for Docker
  • ✅ Pin Python version requirement
  • ✅ Document dependency installation
  • ✅ Test dependency updates before merging
  • ✅ Use dependency groups for organization

Auto-Apply

When managing dependencies:

  1. Use uv or Poetry (not plain pip)
  2. Define dependencies in pyproject.toml
  3. Generate and commit lock file
  4. Use version constraints (^, ~, >=)
  5. Separate dev/docs dependencies
  6. Run security audits (pip-audit)
  7. Set up Dependabot
  8. Test updates in CI before merging
  • python-packaging - For package configuration
  • git-workflow-standards - For version control
  • monitoring-alerting - For dependency monitoring