在 Docker 中使用 uv

快速入门

提示

查看 uv-docker-example 项目，了解在 Docker 中构建应用程序时使用 uv 的最佳实践示例。

uv 提供 distroless（无发行版）Docker 镜像（适用于将 uv 二进制文件复制到您自己的镜像构建中）以及基于流行基础镜像构建的镜像（适用于在容器中使用 uv）。Distroless 镜像除了 uv 二进制文件外不包含任何其他内容。相比之下，派生镜像包含带有预装 uv 的操作系统。

例如，要在基于 Debian 的容器中运行 uv：

$ docker run --rm -it ghcr.io/astral-sh/uv:debian uv --help

可用镜像

提供以下 distroless 镜像

ghcr.io/astral-sh/uv:latest
ghcr.io/astral-sh/uv:{major}.{minor}.{patch}，例如 ghcr.io/astral-sh/uv:0.10.9
ghcr.io/astral-sh/uv:{major}.{minor}，例如 ghcr.io/astral-sh/uv:0.8（最新补丁版本）

并提供以下派生镜像

基于 alpine:3.23
- ghcr.io/astral-sh/uv:alpine
- ghcr.io/astral-sh/uv:alpine3.23
基于 alpine:3.22
- ghcr.io/astral-sh/uv:alpine3.22
基于 debian:trixie-slim
- ghcr.io/astral-sh/uv:debian-slim
- ghcr.io/astral-sh/uv:trixie-slim
基于 buildpack-deps:trixie
- ghcr.io/astral-sh/uv:debian
- ghcr.io/astral-sh/uv:trixie
基于 dhi.io/alpine-base:3.23
- ghcr.io/astral-sh/uv:alpine-dhi
- ghcr.io/astral-sh/uv:alpine3.23-dhi
基于 dhi.io/debian-base:trixie-debian13
- ghcr.io/astral-sh/uv:debian-dhi
- ghcr.io/astral-sh/uv:trixie-dhi
基于 dhi/python:3.x
- ghcr.io/astral-sh/uv:python3.14-dhi
- ghcr.io/astral-sh/uv:python3.13-dhi
- ghcr.io/astral-sh/uv:python3.12-dhi
- ghcr.io/astral-sh/uv:python3.11-dhi
- ghcr.io/astral-sh/uv:python3.10-dhi
基于 python3.x-alpine
- ghcr.io/astral-sh/uv:python3.14-alpine
- ghcr.io/astral-sh/uv:python3.14-alpine3.23
- ghcr.io/astral-sh/uv:python3.13-alpine
- ghcr.io/astral-sh/uv:python3.13-alpine3.23
- ghcr.io/astral-sh/uv:python3.12-alpine
- ghcr.io/astral-sh/uv:python3.12-alpine3.23
- ghcr.io/astral-sh/uv:python3.11-alpine
- ghcr.io/astral-sh/uv:python3.11-alpine3.23
- ghcr.io/astral-sh/uv:python3.10-alpine
- ghcr.io/astral-sh/uv:python3.10-alpine3.23
- ghcr.io/astral-sh/uv:python3.9-alpine
- ghcr.io/astral-sh/uv:python3.9-alpine3.22
基于 python3.x-trixie
- ghcr.io/astral-sh/uv:python3.14-trixie
- ghcr.io/astral-sh/uv:python3.13-trixie
- ghcr.io/astral-sh/uv:python3.12-trixie
- ghcr.io/astral-sh/uv:python3.11-trixie
- ghcr.io/astral-sh/uv:python3.10-trixie
- ghcr.io/astral-sh/uv:python3.9-trixie
基于 python3.x-slim-trixie
- ghcr.io/astral-sh/uv:python3.14-trixie-slim
- ghcr.io/astral-sh/uv:python3.13-trixie-slim
- ghcr.io/astral-sh/uv:python3.12-trixie-slim
- ghcr.io/astral-sh/uv:python3.11-trixie-slim
- ghcr.io/astral-sh/uv:python3.10-trixie-slim
- ghcr.io/astral-sh/uv:python3.9-trixie-slim

与 distroless 镜像一样，每个派生镜像发布的 uv 版本标签格式为 ghcr.io/astral-sh/uv:{major}.{minor}.{patch}-{base} 和 ghcr.io/astral-sh/uv:{major}.{minor}-{base}，例如 ghcr.io/astral-sh/uv:0.10.9-alpine。

此外，从 0.8 版本开始，每个派生镜像还将 UV_TOOL_BIN_DIR 设置为 /usr/local/bin，以确保 uv tool install 能与默认用户一起正常工作。

有关更多详细信息，请参阅 GitHub Container 页面。

安装 uv

使用上述预装有 uv 的镜像之一，或通过从官方 distroless Docker 镜像复制二进制文件来安装 uv

Dockerfile

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

或者，使用安装程序

Dockerfile

FROM python:3.12-slim-trixie

# The installer requires curl (and certificates) to download the release archive
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates

# Download the latest installer
ADD https://astral.org.cn/uv/install.sh /uv-installer.sh

# Run the installer then remove it
RUN sh /uv-installer.sh && rm /uv-installer.sh

# Ensure the installed binary is on the `PATH`
ENV PATH="/root/.local/bin/:$PATH"

注意：这需要系统安装 curl。

无论哪种方式，最佳实践是锁定到特定的 uv 版本，例如：

COPY --from=ghcr.io/astral-sh/uv:0.10.9 /uv /uvx /bin/

提示

虽然上面的 Dockerfile 示例锁定了一个特定的标签，但也可以锁定一个特定的 SHA256。在需要可重现构建的环境中，锁定特定的 SHA256 被认为是最佳实践，因为标签可能会随不同的提交 SHA 而变动。

# e.g., using a hash from a previous release
COPY --from=ghcr.io/astral-sh/uv@sha256:2381d6aa60c326b71fd40023f921a0a3b8f91b14d5db6b90402e65a635053709 /uv /uvx /bin/

或者，使用安装程序

ADD https://astral.org.cn/uv/0.10.9/install.sh /uv-installer.sh

安装项目

如果您正在使用 uv 管理项目，可以将其复制到镜像中并进行安装

Dockerfile

# Copy the project into the image
COPY . /app

# Disable development dependencies
ENV UV_NO_DEV=1

# Sync the project into a new environment, asserting the lockfile is up to date
WORKDIR /app
RUN uv sync --locked

重要

最佳实践是将 .venv 添加到仓库的 .dockerignore 文件中，以防止其包含在镜像构建中。项目的虚拟环境依赖于您的本地平台，应在镜像中从头开始创建。

然后，默认启动您的应用程序

Dockerfile

# Presuming there is a `my_app` command provided by the project
CMD ["uv", "run", "my_app"]

提示

最佳实践是使用中间层将依赖项的安装与项目本身隔离开来，以提高 Docker 镜像的构建速度。

请查看 uv-docker-example 项目中的完整示例。

使用环境

一旦项目安装完成，您可以激活项目虚拟环境（将二进制文件目录置于 PATH 最前面）

Dockerfile

ENV PATH="/app/.venv/bin:$PATH"

或者，对于任何需要该环境的命令，您可以使用 uv run

Dockerfile

RUN uv run some_script.py

提示

此外，在同步之前可以设置 UV_PROJECT_ENVIRONMENT 设置，以安装到系统 Python 环境中，从而完全跳过环境激活。

使用已安装的工具

要使用已安装的工具，请确保工具 bin 目录位于 PATH 中

Dockerfile

ENV PATH=/root/.local/bin:$PATH
RUN uv tool install cowsay

$ docker run -it $(docker build -q .) /bin/bash -c "cowsay -t hello"
  _____
| hello |
  =====
     \
      \
        ^__^
        (oo)\_______
        (__)\       )\/\
            ||----w |
            ||     ||

注意

可以通过在容器中运行 uv tool dir --bin 命令来确定工具 bin 目录的位置。

或者，可以将其设置为一个常量位置

Dockerfile

ENV UV_TOOL_BIN_DIR=/opt/uv-bin/

在容器中开发

在开发时，将项目目录挂载到容器中非常有用。通过此设置，对项目的更改可以立即反映在容器化服务中，而无需重新构建镜像。但是，请务必不要将项目虚拟环境 (.venv) 包含在挂载中，因为虚拟环境是平台特定的，应该保留为镜像构建的版本。

使用 `docker run` 挂载项目

将项目（位于工作目录中）绑定挂载到 /app，同时使用匿名卷保留 .venv 目录

$ docker run --rm --volume .:/app --volume /app/.venv [...]

提示

包含 --rm 标志是为了确保容器退出时清理容器和匿名卷。

请查看 uv-docker-example 项目中的完整示例。

使用 `docker compose` 配置 `watch`

使用 Docker Compose 时，可以使用更复杂的工具进行容器开发。watch 选项比绑定挂载提供了更高的粒度，并支持在文件更改时触发对容器化服务的更新。

注意

此功能需要 Compose 2.22.0，该版本随 Docker Desktop 4.24 提供。

在您的 Docker compose 文件中配置 watch，以在不同步项目虚拟环境的情况下挂载项目目录，并在配置更改时重新构建镜像

compose.yaml

services:
  example:
    build: .

    # ...

    develop:
      # Create a `watch` configuration to update the app
      #
      watch:
        # Sync the working directory with the `/app` directory in the container
        - action: sync
          path: .
          target: /app
          # Exclude the project virtual environment
          ignore:
            - .venv/

        # Rebuild the image on changes to the `pyproject.toml`
        - action: rebuild
          path: ./pyproject.toml

然后，运行 docker compose watch 以开发模式启动容器。

请查看 uv-docker-example 项目中的完整示例。

优化

编译字节码

对于生产镜像，通常希望将 Python 源代码编译为字节码，因为这有助于提高启动时间（代价是增加安装时间和镜像大小）。

要启用字节码编译，请使用 --compile-bytecode 标志

Dockerfile

RUN uv python install --compile-bytecode
RUN uv sync --compile-bytecode

或者，您可以设置 UV_COMPILE_BYTECODE 环境变量，以确保 Dockerfile 中的所有命令都编译字节码

Dockerfile

ENV UV_COMPILE_BYTECODE=1

注意

uv 在 uv python install 期间仅编译受管理 Python 版本的标准库。非受管理 Python 版本的发行商决定标准库是否预编译。例如，官方 python 镜像不会有预编译的标准库。

缓存

缓存挂载 (Cache mount) 可用于提高构建效率

Dockerfile

ENV UV_LINK_MODE=copy

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

更改 UV_LINK_MODE 可以消除关于无法链接文件的警告，因为缓存和同步目标位于不同的文件系统上。

如果您没有挂载缓存，可以通过使用 --no-cache 标志或设置 UV_NO_CACHE 来减小镜像大小。

默认情况下，受管理的 Python 安装在安装前不会被缓存。设置 UV_PYTHON_CACHE_DIR 可以与缓存挂载结合使用

Dockerfile

ENV UV_PYTHON_CACHE_DIR=/root/.cache/uv/python

RUN --mount=type=cache,target=/root/.cache/uv \
    uv python install

注意

可以通过在容器中运行 uv cache dir 命令来确定缓存目录的位置。

或者，可以将缓存设置为一个常量位置

Dockerfile

ENV UV_CACHE_DIR=/opt/uv-cache/

中间层

如果您正在使用 uv 管理项目，可以通过使用 --no-install 选项将传递依赖项的安装移动到其自己的层来提高构建速度。

uv sync --no-install-project 将安装项目的依赖项，但不会安装项目本身。由于项目更改频繁，但其依赖项通常是静态的，这可以节省大量时间。

Dockerfile

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

# Change the working directory to the `app` directory
WORKDIR /app

# Install dependencies
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 the project into the image
COPY . /app

# Sync the project
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked

请注意，pyproject.toml 是识别项目根目录和名称所必需的，但在最终的 uv sync 命令之前，项目内容不会被复制到镜像中。

提示

如果您想在同步中排除特定的附加包，请使用 --no-install-package <name>。

工作区中的中间层

如果您使用的是工作区，则需要进行一些更改

在初始同步期间使用 --frozen 而不是 --locked。
使用 --no-install-workspace 标志，该标志排除项目和所有工作区成员。

Dockerfile

# Install uv
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 --frozen --no-install-workspace

COPY . /app

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

如果没有每个工作区成员的 pyproject.toml 文件，uv 无法断言 uv.lock 文件是最新的，因此我们在初始同步期间使用 --frozen 而不是 --locked 来跳过检查。在所有工作区成员被复制后的下一次同步中，仍然可以使用 --locked 并验证 lockfile 对于所有工作区成员是否正确。

非可编辑安装

默认情况下，uv 以可编辑模式安装项目和工作区成员，因此对源代码的更改会立即反映在环境中。

uv sync 和 uv run 都接受 --no-editable 标志，它指示 uv 以非可编辑模式安装项目，从而移除对源代码的任何依赖。

在多阶段 Docker 镜像的上下文中，可以使用 --no-editable 将项目包含在某个阶段同步的虚拟环境中，然后仅将虚拟环境（而非源代码）复制到最终镜像中。

例如

Dockerfile

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

# Change the working directory to the `app` directory
WORKDIR /app

# Install dependencies
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

# Copy the project into the intermediate image
COPY . /app

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

FROM python:3.12-slim

# Copy the environment, but not the source code
COPY --from=builder --chown=app:app /app/.venv /app/.venv

# Run the application
CMD ["/app/.venv/bin/hello"]

临时使用 uv

如果最终镜像中不需要 uv，可以在每次调用时挂载二进制文件

Dockerfile

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

使用 pip 接口

安装软件包

在容器中，使用系统 Python 环境是安全的，因为容器本身已经隔离。可以使用 --system 标志来安装到系统环境中

Dockerfile

RUN uv pip install --system ruff

要默认使用系统 Python 环境，请设置 UV_SYSTEM_PYTHON 变量

Dockerfile

ENV UV_SYSTEM_PYTHON=1

或者，可以创建并激活一个虚拟环境

Dockerfile

RUN uv venv /opt/venv
# Use the virtual environment automatically
ENV VIRTUAL_ENV=/opt/venv
# Place entry points in the environment at the front of the path
ENV PATH="/opt/venv/bin:$PATH"

使用虚拟环境时，应在 uv 调用中省略 --system 标志

Dockerfile

RUN uv pip install ruff

安装依赖项

要安装需求文件，请将它们复制到容器中

Dockerfile

COPY requirements.txt .
RUN uv pip install -r requirements.txt

安装项目

当同时安装项目和需求文件时，最佳实践是将复制需求文件与复制其余源代码分离开。这样可以将项目的依赖项（不常更改）与项目本身（更改非常频繁）分离开来缓存。

Dockerfile

COPY pyproject.toml .
RUN uv pip install -r pyproject.toml
COPY . .
RUN uv pip install -e .

验证镜像来源

Docker 镜像在构建过程中进行签名，以提供来源证明。这些证明可用于验证镜像是否来自官方渠道。

例如，您可以使用 GitHub CLI 工具 gh 验证证明

$ gh attestation verify --owner astral-sh oci://ghcr.io/astral-sh/uv:latest
Loaded digest sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx for oci://ghcr.io/astral-sh/uv:latest
Loaded 1 attestation from GitHub API

The following policy criteria will be enforced:
- OIDC Issuer must match:................... https://token.actions.githubusercontent.com
- Source Repository Owner URI must match:... https://github.com/astral-sh
- Predicate type must match:................ https://slsa.dev/provenance/v1
- Subject Alternative Name must match regex: (?i)^https://github.com/astral-sh/

✓ Verification succeeded!

sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx was attested by:
REPO          PREDICATE_TYPE                  WORKFLOW
astral-sh/uv  https://slsa.dev/provenance/v1  .github/workflows/build-docker.yml@refs/heads/main

这表明该特定 Docker 镜像是由官方 uv GitHub 发布工作流构建的，且自构建以来未被篡改。

GitHub 证明基于 sigstore.dev 基础设施。因此，您还可以使用 cosign 命令根据 uv 的（多平台）清单来验证证明 blob

$ REPO=astral-sh/uv
$ gh attestation download --repo $REPO oci://ghcr.io/${REPO}:latest
Wrote attestations to file sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.jsonl.
Any previous content has been overwritten

The trusted metadata is now available at sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.jsonl
$ docker buildx imagetools inspect ghcr.io/${REPO}:latest --format "{{json .Manifest}}" > manifest.json
$ cosign verify-blob-attestation \
    --new-bundle-format \
    --bundle "$(jq -r .digest manifest.json).jsonl"  \
    --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
    --certificate-identity-regexp="^https://github\.com/${REPO}/.*" \
    <(jq -j '.|del(.digest,.size)' manifest.json)
Verified OK

提示

这些示例使用了 latest，但最佳实践是验证特定版本标签的证明，例如 ghcr.io/astral-sh/uv:0.10.9，或者（更好的是）特定的镜像摘要，例如 ghcr.io/astral-sh/uv:0.5.27@sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f。