# Uv Package Manager

> Comprehensive uv workflows for Python 3.14 — virtual environments, lockfiles, Python version pinning, monorepo workspaces, Docker integration, CI/CD caching, and migration from pip/Poetry/pip-tools. Use when working with uv beyond basic uv add/uv init.

- Skill: `kumaran-is/uv-package-manager` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kumaran-is/uv-package-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kumaran-is/uv-package-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: kumaran-is (https://skillmd.com/u/kumaran-is)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kumaran-is/uv-package-manager

---


## Iron Law

**ALWAYS USE `uv sync --frozen` IN CI AND DOCKER — never `uv sync` without --frozen in reproducible environments; without it, dependency resolution runs fresh and can pick up different versions**

# uv Package Manager

Deep reference for uv — the ultra-fast Python package manager written in Rust. The workspace uses uv as its primary Python package manager. This skill covers everything beyond the 4 basic commands in `python-dev`.

## When to Use

Load this skill when:
- Setting up lockfile workflows (`uv lock`, `uv sync --frozen`)
- Managing Python version pinning (`uv python pin 3.14`)
- Configuring Docker builds with uv cache mounts
- Setting up GitHub Actions CI with uv dependency caching
- Working in a monorepo with multiple Python packages
- Migrating an existing project from pip, Poetry, or pip-tools
- Using `uv run` to execute scripts without environment activation

The `python-dev` skill covers: `uv init`, `uv add`, basic virtual environment setup. Load THIS skill for everything beyond that.

## Quick Reference

| Task | Command |
|------|---------|
| Create lockfile | `uv lock` |
| Install from lockfile (CI) | `uv sync --frozen` |
| Pin Python version | `uv python pin 3.14` |
| Run without activating | `uv run python script.py` |
| Run tests | `uv run pytest` |
| Upgrade all deps | `uv lock --upgrade` |
| Check outdated | `uv tree --outdated` |
| Remove package | `uv remove <pkg>` |

## Reference File

Load `resources/implementation-playbook.md` for:
- 22 patterns covering all uv workflows
- Virtual environment management (create, activate, uv run)
- Python version management
- Lockfile workflows for reproducible builds
- Monorepo workspace configuration
- Docker multi-stage builds with uv cache mounts
- GitHub Actions CI with uv caching
- Migration guides from pip, Poetry, pip-tools (command-by-command)
- Performance optimization (global cache, parallel install, offline mode)
- Pre-commit hooks and VS Code integration

## Key Patterns Summary

```bash
# New project (from python-dev)
uv init my-service && cd my-service
uv add fastapi uvicorn pydantic pydantic-settings
uv add --dev pytest pytest-asyncio httpx ruff mypy

# Lockfile (add to CI and Docker)
uv lock                          # Generate/update uv.lock
uv sync --frozen                 # Install exact versions from lock

# Python version
uv python pin 3.14               # Write .python-version file
uv python install 3.14           # Install that version

# Run without activating venv
uv run pytest                    # Run pytest
uv run uvicorn src.main:app      # Run server
```

## Docker Pattern (summary — full pattern in playbook)

```dockerfile
FROM python:3.14-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev
```

## CI Pattern (summary — full pattern in playbook)

```yaml
- uses: astral-sh/setup-uv@v4
  with:
    enable-cache: true
- run: uv sync --frozen
```