2025-07-24

[MtkN1]

Today I Learned ...

[MtkN1]

uv with Docker my best pracatice

Main purpose: uv の managed Python (python-build-standalone) を用いた Docker イメージにする。

Notes:

• 殆ど正解の構成は公式の uv-docker-example/standalone.Dockefile にあった。
• 上記から変更した主な工夫点としては:
  • builder stage を非 slim イメージにする (wheel が足りてないパッケージをビルドできるように)
  • .python-version をバインドして指定の managed Python をインストールする
  • 弊アプリケーションはパッケージ化を前提にしているのでそれに適した RUN 命令にする
  • 最終イメージサイズ削減の為に distroless イメージ (cc バリアント¹) を使ってみた
  • Docker Init にあるベストプラクティス ENV 命令を追加

distroless イメージを使うことで aiohttp での最小 Hello world アプリケーションが 141MB (debian:bookworm-slim) -> 121MB (-20MB) になった。 ただサイズは 100MB 切らっておらず bookworm-slim とそんな大差はない, python-build-standalone のバイナリが 100MB 以上ある模様 (distroless/python もあるけど今回の趣旨的に案からは除外)。 実行時の影響も未検証で不明, 安定性を考えると bookworm-slim でもいいかも。 ただ nonroot ユーザーが作成済みなのはラクできる。

Dockerfile

# An example of using standalone Python builds with multistage images.

# First, build the application in the `/app` directory
FROM ghcr.io/astral-sh/uv:bookworm AS builder
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy

# Configure the Python directory so it is consistent
ENV UV_PYTHON_INSTALL_DIR=/python

# Only use the managed Python version
ENV UV_PYTHON_PREFERENCE=only-managed

# Install Python before the project for caching
WORKDIR /app
RUN --mount=type=bind,source=.python-version,target=.python-version \
    uv python install
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=.python-version,target=.python-version \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-dev
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=.python-version,target=.python-version \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    --mount=type=bind,source=src,target=src \
    --mount=type=bind,source=README.md,target=README.md \
    uv sync --locked --no-editable --no-dev

# Then, use a final image without uv
FROM gcr.io/distroless/cc-debian12:nonroot AS runtime

# Copy the Python version
COPY --from=builder --chown=root:root /python /python

# Copy the application from the builder
COPY --from=builder --chown=root:root /app /app

# Place executables in the environment at the front of the path
ENV PATH="/app/.venv/bin:$PATH"

# Prevents Python from writing pyc files.
ENV PYTHONDONTWRITEBYTECODE=1

# Keeps Python from buffering stdout and stderr to avoid situations where
# the application crashes without emitting any logs due to buffering.
ENV PYTHONUNBUFFERED=1

# Run the application.
CMD ["python", "-m", "uv_docker_example"]

Footnotes

1. cc バリアントより小さいバリアント (base, static) はエラーになった。 ↩