前言 / Introduction

在使用 uv container 開發 Python 專案時，可以透過一些技巧優化 build 時間與最終 image 的大小。 本篇將介紹三種常用方式：Intermediate Layers、Non-editable Installs、臨時使用 uv。

1. 利用 Intermediate Layers 提升 Build 速度

專案本身會頻繁變動，但依賴通常較穩定，可以將依賴安裝分離成獨立 Docker layer：

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
WORKDIR /app

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

ADD . /app

RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked

Note:

  • --no-install-workspace：排除 workspace 成員
  • --no-install-package <name>：排除特定套件
  • pyproject.toml 必須複製進 image，以識別專案根目錄和名稱

2. 非編輯模式安裝（Non-editable Installs）

使用 –no-editable 可以只安裝虛擬環境，減少最終 image 大小：

# Builder stage
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
WORKDIR /app

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 --no-editable

ADD . /app

RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-editable

# Final stage
FROM python:3.12-slim
COPY --from=builder --chown=app:app /app/.venv /app/.venv
CMD ["/app/.venv/bin/hello"]

3. 臨時使用 uv

如果 uv 只在 build 階段需要，而不需出現在最終 image，可以將 uv binary mount：

RUN --mount=from=ghcr.io/astral-sh/uv,source=/uv,target=/bin/uv \
    uv sync

這樣最終 image 不會帶 uv，減少體積，也避免暴露開發工具。

結語

這些優化技巧可以讓你的 uv Docker 建構更快、更小、更有效率。

  • Intermediate layers：將依賴安裝與專案分離，加快 rebuild

  • Non-editable installs：只包含虛擬環境，縮小 image

  • 臨時使用 uv：最終 image 不帶開發工具，保持乾淨

結合基礎篇介紹的 uv container 使用方式，可以打造既快速又輕量的 Python Docker 開發環境。

更多資源可以參考官方文件：

回到 uv Container 基礎篇 了解更多基礎用法。