xtulnx/uv repository overview

⁠uv Python Runner

这是一个面向 Python 项目的 uv 运行镜像，适合直接挂载项目目录后执行：

• python
• pytest
• ruff
• uvicorn
• 任何其他需要在项目虚拟环境中运行的命令

镜像内置 uv 和 curl，不包含 uvx。如果你需要运行工具，请使用 uv tool run ...。

⁠镜像变体

这个仓库会发布同一仓库下的多个 uv 变体，它们共享一个 Docker Hub README。

• xtulnx/uv:latest、xtulnx/uv:0.12、xtulnx/uv:0.12.5 说明：标准精简版，不预装 Python，不安装 git。
• xtulnx/uv:py312、xtulnx/uv:0.12-py312、xtulnx/uv:0.12.5-py312 说明：预装 Python 3.12，不安装 git。
• xtulnx/uv:py312-git、xtulnx/uv:0.12-py312-git、xtulnx/uv:0.12.5-py312-git 说明：预装 Python 3.12，并安装 git。

这些 tag 会一起发布 linux/amd64 和 linux/arm64 多架构镜像。

下面的示例默认使用标准精简版 xtulnx/uv:latest。如果你需要预装 Python 或 git，把 tag 换成对应变体即可。

⁠默认行为

这个镜像的入口规则是：

• docker run ... python main.py 会自动变成 uv run python main.py
• docker run ... pytest 会自动变成 uv run pytest
• docker run ... uv sync 会直接执行原生 uv sync
• docker run ... sh 会进入 shell，不额外包一层 uv run

因此它更偏向“直接运行项目命令”，而不是把每个 uv 子命令都手动写全。

⁠内置配置

• 预装 uv 和 curl
• 工作目录：/workspace
• 默认包索引镜像：清华 PyPI mirror
• uv 的链接模式默认设为 copy，更适合容器挂载目录的使用方式
• 默认启用 uv 托管 Python，并在需要时自动下载
• uv tool install 安装的命令会放入 /usr/local/bin，可直接从 PATH 调用

标准精简版不会在构建阶段预装任何 Python 版本。第一次运行项目命令时，uv 会根据 .python-version、requires-python 或命令需求自动安装对应解释器。py312 和 py312-git 变体会预装 Python 3.12。

⁠目录约定

这个镜像里有几个值得关注的目录：

• /workspace：默认工作目录。建议把你的 Python 项目挂载到这里。
• /root/.cache/uv：uv 总缓存目录，包含包缓存和元数据缓存。
• /root/.cache/uv/python：托管 Python 安装包的下载缓存目录。
• /opt/uv/python：托管 Python 的实际安装目录。
• /usr/local/bin：托管 Python 可执行文件的链接目录。

如果你希望在多个容器运行之间复用缓存和 Python 解释器，建议挂载这些目录：

docker run --rm -it \
  -v "$(pwd):/workspace" \
  -v uv-cache:/root/.cache/uv \
  -v uv-python:/opt/uv/python \
  xtulnx/uv:latest \
  python -V

⁠快速开始

假设当前目录就是你的 Python 项目：

IMAGE=xtulnx/uv:latest

docker run --rm -it \
  -v "$(pwd):/workspace" \
  "$IMAGE" \
  python main.py

如果项目是基于 pyproject.toml 的 uv 项目，直接运行测试也可以：

IMAGE=xtulnx/uv:latest

docker run --rm -it \
  -v "$(pwd):/workspace" \
  "$IMAGE" \
  pytest

⁠docker compose 示例

如果你更习惯用 docker compose 管理本地运行环境，可以使用下面这个通用示例：

services:
  app:
    image: xtulnx/uv:latest
    working_dir: /workspace
    stdin_open: true
    tty: true
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./:/workspace
      - uv-cache:/root/.cache/uv
      - uv-python:/opt/uv/python

volumes:
  uv-cache:
  uv-python:

保存为 docker-compose.yml 后，常见用法如下。

先同步依赖：

docker compose run --rm app uv sync

运行项目：

docker compose run --rm app python main.py

如果你的项目是 Web 服务，也可以直接在 compose 里补端口和默认命令：

services:
  app:
    image: xtulnx/uv:latest
    working_dir: /workspace
    command: uvicorn app:app --host 0.0.0.0 --port 8000
    ports:
      - "8000:8000"
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./:/workspace
      - uv-cache:/root/.cache/uv
      - uv-python:/opt/uv/python

volumes:
  uv-cache:
  uv-python:

⁠常用示例

先同步依赖：

IMAGE=xtulnx/uv:latest

docker run --rm -it \
  -v "$(pwd):/workspace" \
  "$IMAGE" \
  uv sync

运行模块：

IMAGE=xtulnx/uv:latest

docker run --rm -it \
  -v "$(pwd):/workspace" \
  "$IMAGE" \
  python -m your_package

启动 uvicorn：

IMAGE=xtulnx/uv:latest

docker run --rm -it \
  -p 8000:8000 \
  -v "$(pwd):/workspace" \
  "$IMAGE" \
  uvicorn app:app --host 0.0.0.0 --port 8000

显式使用 uv 子命令：

IMAGE=xtulnx/uv:latest

docker run --rm -it \
  -v "$(pwd):/workspace" \
  "$IMAGE" \
  uv python list

⁠自动安装 Python

如果项目根目录存在 .python-version，或者 pyproject.toml 里声明了 Python 版本要求，uv 会按需安装对应版本。

例如：

echo 3.13 > .python-version

docker run --rm -it \
  -v "$(pwd):/workspace" \
  xtulnx/uv:latest \
  python -V

首次运行时如果本地还没有该版本，uv 会自动下载并安装。

⁠镜像与下载配置

镜像已经默认把 Python 包索引配置成了清华镜像。如果你需要覆盖它，可以在运行时传环境变量：

docker run --rm -it \
  -e UV_DEFAULT_INDEX=https://pypi.org/simple \
  -v "$(pwd):/workspace" \
  xtulnx/uv:latest \
  python -V

如果你还想覆盖托管 Python 的下载源，也可以显式传入：

docker run --rm -it \
  -e UV_PYTHON_INSTALL_MIRROR=https://your-mirror.example.com/python-build-standalone \
  -v "$(pwd):/workspace" \
  xtulnx/uv:latest \
  python -V

UV_PYTHON_INSTALL_MIRROR 的参考值：

• https://gh-proxy.org/https://github.com/astral-sh/python-build-standalone/releases/download
• https://ghfast.top/https://github.com/astral-sh/python-build-standalone/releases/download

根据 uv 官方文档，这个变量会替换默认前缀 https://github.com/astral-sh/python-build-standalone/releases/download，用于托管 Python 的下载源配置。

⁠Git 依赖说明

标准精简版和 py312 变体里故意没有安装 git。这意味着：

• 你的项目源码管理应在主机上完成
• 如果依赖全部来自 PyPI 或兼容索引，通常没有问题
• 如果依赖里包含 git+https://... 这类 VCS 依赖，uv sync 或 uv run 解析这类依赖时可能失败

如果你需要 Git 依赖，可以直接使用 py312-git 变体；如果还需要其他 Python 版本，则建议基于标准精简版派生项目专用镜像并安装 git。

⁠本地编译依赖说明

镜像里也没有 gcc、build-essential、pkg-config 这类编译工具链。这意味着：

• 纯 Python 依赖或已有预编译 wheel 的依赖最适合这个镜像
• 需要在安装阶段现编译本地扩展的依赖，可能无法直接安装

如果你的项目依赖需要本地编译，建议基于这个镜像再派生一个带编译工具链的项目专用镜像。

⁠说明

• 这个镜像默认以 root 身份运行，适合本地开发、CI 和临时任务。