Claude
Skills
Sign in
Back

uv-docker

Included with Lifetime
$97 forever

Guide uv-based multi-stage Dockerfile builds. Use when writing a Dockerfile that installs Python deps via uv.

Cloud & DevOps

What this skill does


# Python Docker Images with uv

Use multi-stage builds with uv. The final image should NOT contain uv — only the installed venv.

## Multi-Stage Build

```dockerfile
# 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:
- Final image has no uv, no cache, no build tools
- Runtime image must use the same Python version as the builder
- `UV_COMPILE_BYTECODE=1` — pre-compile .pyc for faster startup
- `UV_LINK_MODE=copy` — required when cache mount is on a different filesystem
- `UV_PYTHON_DOWNLOADS=0` — use system Python, no managed downloads
- `UV_NO_DEV=1` — omit development dependencies
- `--locked` — ensure lockfile is up-to-date, fail otherwise
- Run as non-root user in production

## .dockerignore

```
.venv
__pycache__
```

## Reference

If more detail is needed, consult:
- https://docs.astral.sh/uv/guides/integration/docker/
- https://github.com/astral-sh/uv-docker-example/blob/main/multistage.Dockerfile

Related in Cloud & DevOps