Stats
Actions
Tags
From uv-features
This skill should be used when the user asks to "use uv in Docker", "write a Dockerfile with uv", "uv sync in Docker", "uv multi-stage build", or when writing a Dockerfile that uses uv for Python dependency installation. Guides uv-based multi-stage container builds.
How this skill is triggered — by the user, by Claude, or both
Slash command
/uv-features:uv-dockerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use multi-stage builds with uv. The final image should NOT contain uv — only the installed venv.
Use multi-stage builds with uv. The final image should NOT contain uv — only the installed venv.
# Stage 1: Build
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_NO_DEV=1 UV_PYTHON_DOWNLOADS=0
WORKDIR /app
# Install dependencies first (cached layer)
RUN --mount=type=cache,target=/root/.cache/uv \
--mount=type=bind,source=uv.lock,target=uv.lock \
--mount=type=bind,source=pyproject.toml,target=pyproject.toml \
uv sync --locked --no-install-project
# Copy source and install project
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked
# Stage 2: Runtime (no uv, no build tools)
# IMPORTANT: Use the same Python version as the builder
FROM python:3.12-slim-bookworm
RUN groupadd --system --gid=999 nonroot \
&& useradd --system --gid=999 --uid=999 --create-home nonroot
COPY --from=builder --chown=nonroot:nonroot /app /app
ENV PATH="/app/.venv/bin:$PATH"
USER nonroot
WORKDIR /app
CMD ["python", "main.py"]
Key points:
UV_COMPILE_BYTECODE=1 — pre-compile .pyc for faster startupUV_LINK_MODE=copy — required when cache mount is on a different filesystemUV_PYTHON_DOWNLOADS=0 — use system Python, no managed downloadsUV_NO_DEV=1 — omit development dependencies--locked — ensure lockfile is up-to-date, fail otherwise.venv
__pycache__
If more detail is needed, consult:
npx claudepluginhub pokutuna/claude-plugins --plugin uv-featuresManages Python projects with Astral's uv: dependencies via pyproject.toml, PEP 723 scripts, virtualenvs, Python versions, tool installs, pip/poetry migrations, CI/CD, Docker setup.
Guides uv usage for fast Python package installation, dependency resolution, virtual environments, lockfiles, monorepos, and CI/CD/Docker optimization.
Optimizes Python Docker images with slim bases (not Alpine), multi-stage builds using uv/poetry/pip, virtual environments, reducing sizes from ~1GB to 80-120MB. For Python container Dockerfiles.