用 uv 替代 pip + virtualenv，配合多阶段构建和 UV_NO_DEV=1 等环境变量控制，可将 Python 镜像体积压缩至原 pip 构建的 30%–40%，核心在于避免重复安装、剔除开发依赖、隔离缓存且不打包构建工具。
直接说结论：用 uv 替代 pip + virtualenv，配合多阶段构建和环境变量控制，能将 Python 镜像体积压到原 pip 构建的 30%–40% 左右。关键不在“装得少”，而在“不重复装、不带缓存、不拖构建工具”。
uv sync --locked 比 pip install -r requirements.txt 少写 3 层镜像
传统 pip install 在 Dockerfile 中常这样写：
COPY requirements.txt . RUN pip install -r requirements.txt COPY . .
这会把 requirements.txt 和安装过程中的临时文件（如 .whl 解压中间态、__pycache__）全打进镜像层。而 uv sync --locked 默认只写最终的已安装包，且支持 --no-install-project 分离依赖与代码安装。
- 必须先有
uv.lock文件（由uv lock生成），否则--locked会报错：Error: no lockfile found at uv.lock - 推荐在构建阶段用
RUN uv sync --locked --no-install-project，再COPY . /app，最后RUN uv sync --locked—— 这样只有代码变更才触发重装，依赖层完全复用 -
uv sync不会生成pip那种冗余的dist-info元数据目录结构，实际磁盘占用更紧凑
UV_NO_DEV=1 环境变量真能砍掉几百MB
很多项目 pyproject.toml 里写了 [project.optional-dependencies]，比如 dev = ["ruff", "pytest", "mypy"]。默认 uv sync 会全装，但生产镜像根本不需要这些。
Python uv 0.12.20 是 Astral 开发的 Python 包与项目管理工具，支持依赖解析、虚拟环境、Python 版本及项目锁文件管理。本下载包适用于 Windows x64，解压后可使用 uv 命令。
- 在 Dockerfile 中加
ENV UV_NO_DEV=1，uv sync就自动跳过所有optional-dependencies里的项 - 对比实测：一个含 12 个 dev 工具的项目，开启后镜像减少 427MB（来自 uv-docker-example 的 benchmark 数据）
- 注意：如果项目用
uv run --with ruff myscript.py做 CI 检查，那 CI 阶段要单独关掉UV_NO_DEV，别误伤
多阶段构建时，千万别把 /root/.cache/uv 打进运行镜像
uv 的全局缓存（UV_CACHE_DIR）默认在用户目录下，Docker 构建中若没显式清理或隔离，很容易被 COPY 或整个文件系统打包带入最终镜像。
- 务必在构建阶段用
--mount=type=cache,target=/root/.cache/uv，而不是COPY --from=builder /root/.cache/uv /root/.cache/uv - 运行阶段的基础镜像（如
python:3.12-slim-trixie）里根本不该有/root/.cache/uv—— 它只对构建有意义 - 如果用了
uv python install下 Python 解释器，也要确保UV_PYTHON_INSTALL_DIR指向构建阶段专用路径，别混进运行镜像
基础镜像选 ghcr.io/astral-sh/uv:python3.12-trixie-slim 而不是 python:3.12-slim
官方 python:3.12-slim 镜像不含 uv，你得自己 RUN pipx install uv —— 这会额外引入 pipx、venv、Python 构建依赖（如 gcc、libc-dev），白占 80MB+。
- 直接用
ghcr.io/astral-sh/uv:python3.12-trixie-slim，它预装uv+ 精简版python3.12，体积比标准 slim 小约 25% - 这个镜像基于 Debian Trixie，glibc 版本新，兼容性好，且不含
apt、curl等非必需工具（你真要用，再apt-get update && apt-get install -y单独装） - 注意：别用
ghcr.io/astral-sh/uv:latest，tag 不固定会导致构建不可重现；固定用python3.12-trixie-slim或带 commit hash 的版本
最易被忽略的一点：uv 的缓存机制依赖硬链接，而某些容器运行时（如旧版 Podman 或 rootless Docker）在 overlayfs 上可能禁用硬链接。如果发现 uv venv 创建的环境体积异常大，先检查 stat -c "%h" venv/bin/python 输出是否为 1 —— 是的话，说明硬链接失效，uv 回退成全量复制，空间优势就没了。
