共计 14878 个字符，预计需要花费 38 分钟才能阅读完成。

uv 是 Astral 团队开发的极速 Python 包管理器，用 Rust 编写，速度比 pip 快 10-100 倍。它集成了 pip、pip-tools、virtualenv、pyenv、pipx 等工具的全部功能，目标是成为 Python 项目的「一站式」工具链。

• 安装与更新
• 项目管理
  • uv init — 创建项目
  • uv add — 添加依赖
  • uv remove — 移除依赖
  • uv sync — 同步环境
  • uv lock — 锁定依赖
  • uv run — 运行命令
  • uv export — 导出锁文件
  • uv tree — 依赖树
  • uv version — 版本管理
• Python 版本管理
  • uv python install — 安装 Python
  • uv python list — 列出 Python
  • uv python pin — 固定版本
  • uv python find — 查找 Python
  • uv python uninstall — 卸载 Python
• 虚拟环境
• pip 兼容接口
• 工具管理 (pipx 替代)
• 构建与发布
  • uv build — 构建
  • uv publish — 发布
• 缓存管理
• 配置文件
• 环境变量参考
• PEP 723 内联脚本元数据
• 工作区 (Workspace)
• 常见场景速查
• 与传统工具对比
• 故障排除

---

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

pip install uv

uv self update

uv self version
# 或
uv --version

uv 默认安装在 ~/.local/bin/ (Windows 为 C:Users< 用户 >.localbin)，包含三个可执行文件：

文件	说明
uv	主命令
uvx	快速运行 Python CLI 工具（类似 pipx）
uvw	Windows 包装器

---

uv 的项目管理围绕 pyproject.toml 和 uv.lock 两个核心文件展开。

# 在当前目录创建项目
uv init

# 在指定目录创建项目
uv init my-project

# 创建应用项目 (默认)
uv init --app my-app

# 创建库项目
uv init --lib my-lib

# 创建可打包的项目 (含 src 结构)
uv init --package my-package

# 创建脚本
uv init --script my-script

# 指定构建后端
uv init --build-backend hatch
uv init --build-backend maturin    # Rust 混合项目
uv init --build-backend scikit     # 科学计算项目

# 指定名称和描述
uv init --name my-project --description "A cool project"

# 跳过 git 初始化
uv init --vcs none

# 跳过 README
uv init --no-readme

# 不固定 Python 版本
uv init --no-pin-python

# 指定 Python 版本
uv init -p 3.12

# 仅创建 pyproject.toml (不创建其他文件)
uv init --bare

init 会创建以下文件：

my-project/
├── .python-version    # 固定的 Python 版本
├── pyproject.toml     # 项目配置
├── README.md
├── hello.py           # 示例入口
└── uv.lock            # 自动生成的锁文件 

# 添加依赖
uv add requests

# 添加指定版本
uv add "requests>=2.31"
uv add "requests==2.31.0"

# 添加多个依赖
uv add requests flask numpy

# 添加开发依赖
uv add pytest --dev

# 添加可选依赖 (extras)
uv add requests --optional http

# 添加到指定分组
uv add mypy --group linting

# 从 Git 仓库添加
uv add git+https://github.com/user/repo
uv add git+https://github.com/user/repo --tag v1.0
uv add git+https://github.com/user/repo --branch main
uv add git+https://github.com/user/repo --rev abc123

# 添加时指定 extras
uv add requests --extra socks

# 以可编辑模式添加
uv add --editable ../local-package

# 从 requirements.txt 批量添加
uv add -r requirements.txt

# 不自动同步虚拟环境
uv add requests --no-sync

# 向指定脚本添加依赖 (PEP 723)
uv add requests --script my-script.py

# 添加到工作区中的指定包
uv add requests --package sub-package

# 移除依赖
uv remove requests

# 移除开发依赖
uv remove pytest --dev

# 移除可选依赖
uv remove requests --optional http

# 移除指定分组中的依赖
uv remove mypy --group linting

# 从脚本中移除依赖
uv remove requests --script my-script.py

# 不自动同步
uv remove requests --no-sync

# 从工作区指定包中移除
uv remove requests --package sub-package

根据 uv.lock 同步虚拟环境，确保安装的包与锁文件一致。

# 基本同步
uv sync

# 包含所有可选依赖
uv sync --all-extras

# 包含指定可选依赖
uv sync --extra http

# 排除开发依赖
uv sync --no-dev

# 仅安装开发依赖
uv sync --only-dev

# 包含指定分组
uv sync --group linting

# 仅安装指定分组
uv sync --only-group linting

# 所有分组
uv sync --all-groups

# 精确同步 (移除多余包)
uv sync --exact

# 锁定模式 (确保 uv.lock 不变)
uv sync --locked

# 冻结模式 (不更新 uv.lock)
uv sync --frozen

# 检查是否已同步 (不实际执行)
uv sync --check

# 干运行
uv sync --dry-run

# 同步所有工作区包
uv sync --all-packages

# 同步指定包
uv sync --package sub-package

# 不安装项目本身
uv sync --no-install-project

# 编译字节码 (加速启动)
uv sync --compile-bytecode

# 指定 Python 版本
uv sync -p 3.12

# 同步脚本环境
uv sync --script my-script.py

# 以非可编辑模式安装
uv sync --no-editable

解析依赖并生成 / 更新 uv.lock 文件，不安装包。

# 更新锁文件
uv lock

# 检查锁文件是否最新
uv lock --check

# 检查锁文件是否存在
uv lock --check-exists

# 干运行 (不写入文件)
uv lock --dry-run

# 允许升级
uv lock --upgrade

# 升级指定包
uv lock --upgrade-package requests

# 最低版本解析
uv lock --resolution lowest

# 允许预发布版本
uv lock --prerelease allow

# 锁定脚本依赖
uv lock --script my-script.py

# 指定 Python 版本
uv lock -p 3.12

在项目虚拟环境中运行命令或脚本，自动同步环境。

# 运行 Python
uv run python hello.py

# 运行模块
uv run -m http.server

# 运行项目入口
uv run my-script

# 运行时包含额外依赖
uv run --with requests python app.py

# 运行时包含可编辑依赖
uv run --with-editable ../local-pkg python app.py

# 从 requirements.txt 加载额外依赖
uv run --with-requirements extra.txt python app.py

# 运行 Python 脚本 (PEP 723)
uv run --script my-script.py

# 隔离运行 (临时虚拟环境)
uv run --isolated python app.py

# 不自动同步
uv run --no-sync python app.py

# 锁定 / 冻结模式
uv run --locked python app.py
uv run --frozen python app.py

# 指定 Python 版本
uv run -p 3.11 python app.py

# 包含所有可选依赖
uv run --all-extras python app.py

# 加载 .env 文件
uv run --env-file .env python app.py

# 不加载 .env
uv run --no-env-file python app.py

# 包含指定分组
uv run --group linting python app.py

# 运行 GUI 脚本
uv run --gui-script my-gui.py

# 所有工作区包
uv run --all-packages python app.py

# 运行指定包的命令
uv run --package sub-pkg python app.py

# 编译字节码
uv run --compile-bytecode python app.py

将 uv.lock 导出为兼容格式（如 requirements.txt）。

# 导出为 requirements.txt
uv export

# 导出为 pylock.toml
uv export --format pylock.toml

# 导出到文件
uv export -o requirements.txt

# 包含所有可选依赖
uv export --all-extras

# 包含指定可选依赖
uv export --extra http

# 排除开发依赖
uv export --no-dev

# 仅开发依赖
uv export --only-dev

# 包含所有分组
uv export --all-groups

# 排除哈希
uv export --no-hashes

# 排除注释
uv export --no-annotate

# 排除头部
uv export --no-header

# 以非可编辑模式导出
uv export --no-editable

# 不导出项目本身
uv export --no-emit-project

# 导出指定包
uv export --package sub-pkg

# 导出所有工作区包
uv export --all-packages

# 锁定 / 冻结模式
uv export --locked
uv export --frozen

# 导出脚本依赖
uv export --script my-script.py

# 修剪指定包
uv export --prune some-package

显示项目的依赖关系树。

# 显示依赖树
uv tree

# 跨平台依赖树
uv tree --universal

# 指定深度
uv tree --depth 3

# 仅显示指定包
uv tree --package requests

# 反向依赖 (谁依赖了此包)
uv tree --invert --package requests

# 显示过时版本
uv tree --outdated

# 排除开发依赖
uv tree --no-dev

# 仅开发依赖
uv tree --only-dev

# 指定分组
uv tree --group linting

# 不去重
uv tree --no-dedupe

# 修剪指定包
uv tree --prune some-package

# 指定 Python 版本过滤
uv tree --python-version 3.12

# 指定平台过滤
uv tree --python-platform linux

# 查看当前版本
uv version

# 设置版本
uv version 2.0.0

# 按语义版本升级
uv version --bump major    # 1.0.0 -> 2.0.0
uv version --bump minor    # 1.0.0 -> 1.1.0
uv version --bump patch    # 1.0.0 -> 1.0.1

# 干运行
uv version --dry-run 2.0.0

# 简短输出
uv version --short

# JSON 输出
uv version --output-format json

---

uv 可以自动下载和管理 Python 版本，替代 pyenv。

# 安装最新稳定版
uv python install

# 安装指定版本
uv python install 3.12
uv python install 3.11
uv python install 3.10

# 安装多个版本
uv python install 3.12 3.11 3.10

# 安装 PyPy
uv python install pypy3.10

# 安装指定实现
uv python install 3.12 --implementation cpython

# 列出可用版本
uv python list

# 仅列出已安装版本
uv python list --only-installed

# 仅列出可下载版本
uv python list --only-downloads

# 过滤版本
uv python list 3.12

# 固定 Python 版本 (写入 .python-version)
uv python pin 3.12

# 固定精确版本
uv python pin 3.12.4

# 固定到已安装的版本
uv python pin --no-downloads 3.12

# 查找 Python 解释器
uv python find

# 查找指定版本
uv python find 3.12

# 查找系统 Python
uv python find --system 3.12

# 卸载指定版本
uv python uninstall 3.10

# 卸载所有 uv 管理的 Python
uv python uninstall --all

uv 选择 Python 版本的顺序：

1. --python / -p 命令行参数
2. UV_PYTHON 环境变量
3. .python-version 文件 (uv python pin 创建)
4. pyproject.toml 中的 requires-python
5. 系统 PATH 中的 Python
6. uv 自动下载的 Python (可通过 --no-python-downloads 禁用 )

---

# 创建默认虚拟环境 (.venv)
uv venv

# 指定路径
uv venv my-env

# 指定 Python 版本
uv venv -p 3.12
uv venv --python 3.11

# 安装 seed 包 (pip, setuptools, wheel)
uv venv --seed

# 自定义提示词
uv venv --prompt my-project

# 允许访问系统 site-packages
uv venv --system-site-packages

# 可迁移的虚拟环境
uv venv --relocatable

# 允许已存在的环境
uv venv --allow-existing

# 不关联项目
uv venv --no-project

# 使用 uv 管理的 Python
uv venv --managed-python

# 禁用 Python 自动下载
uv venv --no-python-downloads

---

uv pip 提供与 pip 完全兼容的命令接口，适合迁移或不需要项目管理的场景。

# 安装包
uv pip install requests

# 安装指定版本
uv pip install "requests>=2.31"

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 安装多个包
uv pip install requests flask numpy

# 以可编辑模式安装
uv pip install -e .

# 从 URL 安装
uv pip install https://example.com/package.whl

# 从 Git 安装
uv pip install git+https://github.com/user/repo

# 升级已安装的包
uv pip install --upgrade requests

# 强制重新安装
uv pip install --force-reinstall requests

# 编译字节码
uv pip install --compile-bytecode requests

# 卸载包
uv pip uninstall requests

# 卸载多个包
uv pip uninstall requests flask

# 从 requirements.txt 批量卸载
uv pip uninstall -r requirements.txt

替代 pip-compile，将 requirements.in 编译为 requirements.txt。

# 编译依赖
uv pip compile requirements.in

# 输出到文件
uv pip compile requirements.in -o requirements.txt

# 允许升级
uv pip compile requirements.in --upgrade

# 升级指定包
uv pip compile requirements.in --upgrade-package requests

# 最低版本解析
uv pip compile requirements.in --resolution lowest

# 生成 pylock.toml
uv pip compile requirements.in -o pylock.toml

根据 requirements.txt 同步环境，移除不在文件中的包。

# 同步环境
uv pip sync requirements.txt

# 同步 pylock.toml
uv pip sync pylock.toml

# 列出已安装包 (requirements 格式)
uv pip freeze

# 输出到文件
uv pip freeze -o requirements.txt

# 列出已安装包 (表格格式)
uv pip list

# 显示过时包
uv pip list --outdated

# 显示包详情
uv pip show requests

# 显示依赖关系
uv pip show requests --tree

# 显示依赖树
uv pip tree

# 反向依赖
uv pip tree --invert

# 检查依赖兼容性
uv pip check

---

uv tool 和 uvx 用于在隔离环境中运行和安装 Python CLI 工具。

一次性运行工具，不永久安装。

# 运行工具
uv tool run ruff check
uvx ruff check

# 运行指定版本
uvx [email protected] check

# 从 Git 运行
uvx --from git+https://github.com/user/repo tool-name

# 指定 Python 版本
uvx -p 3.12 ruff check

# 运行时带额外依赖
uvx --with requests httpx-cli

永久安装工具到 ~/.local/bin/。

# 安装工具
uv tool install ruff

# 安装指定版本
uv tool install [email protected]

# 安装带 extras
uv tool install black --extra colorama

# 从 Git 安装
uv tool install --from git+https://github.com/user/repo tool-name

# 指定 Python 版本
uv tool install -p 3.12 ruff

# 安装时带额外依赖
uv tool install ruff --with mypy

# 强制重新安装
uv tool install ruff --force

# 更新 PATH (确保 ~/.local/bin 在 PATH 中)
uv tool update-shell

# 列出已安装工具
uv tool list

# 显示详细信息
uv tool list --show-paths

# 升级所有工具
uv tool upgrade

# 升级指定工具
uv tool upgrade ruff

# 升级并重新安装
uv tool upgrade --reinstall ruff

# 卸载工具
uv tool uninstall ruff

# 卸载所有工具
uv tool uninstall --all

# 查看工具安装目录
uv tool dir

---

将项目构建为源分发 (sdist) 和二进制分发 (wheel)。

# 构建 sdist 和 wheel
uv build

# 仅构建 sdist
uv build --sdist

# 仅构建 wheel
uv build --wheel

# 指定输出目录
uv build --out-dir dist/

# 构建指定目录的项目
uv build /path/to/project

# 构建工作区中的指定包
uv build --package sub-pkg

# 构建所有工作区包
uv build --all-packages

# 指定构建后端设置
uv build -C key=value

# 不显示构建日志
uv build --no-build-logs

# 指定 Python 版本
uv build -p 3.12

将构建产物上传到包索引 (如 PyPI)。

# 发布到 PyPI
uv publish

# 发布指定文件
uv publish dist/my-package-1.0.tar.gz dist/my_package-1.0-py3-none-any.whl

# 指定用户名 / 密码
uv publish --username __token__ --password pypi-token

# 使用 token
uv publish --token pypi-token

# 发布到自定义索引
uv publish --publish-url https://my-index.example.com/upload/

# 发布到配置中的指定索引
uv publish --index my-private-index

# 检查是否已存在 (跳过重复)
uv publish --check-url https://pypi.org/simple/

# GitHub Actions 可信发布
uv publish --trusted-publishing always

# 使用 keyring
uv publish --keyring-provider subprocess

---

uv 使用全局缓存来避免重复下载和解包。

# 查看缓存目录
uv cache dir

# 清理所有缓存
uv cache clean

# 清理指定包缓存
uv cache clean requests

# 清理不可达对象
uv cache prune

# 禁用缓存 (临时)
uv --no-cache pip install requests

# 指定缓存目录
uv --cache-dir /path/to/cache pip install requests

# 刷新所有缓存数据
uv --refresh pip install requests

# 刷新指定包缓存
uv --refresh-package requests pip install requests

缓存默认位置：

• macOS: ~/Library/Caches/uv
• Linux: ~/.cache/uv (遵循 $XDG_CACHE_HOME)
• Windows: %LOCALAPPDATA%uvCache

---

uv 支持两种配置文件：

项目级配置，在 [tool.uv] 下：

[project]
name = "my-project"
version = "1.0.0"
requires-python = ">=3.12"
dependencies = ["requests>=2.31",]

[tool.uv]
dev-dependencies = ["pytest>=7.0",]

# 自定义包源
[tool.uv.sources]
my-local-pkg = {path = "../my-local-pkg", editable = true}
my-git-pkg = {git = "https://github.com/user/repo", tag = "v1.0"}

# 自定义索引
[[tool.uv.index]]
name = "private"
url = "https://private.pypi.example.com/simple/"

# 依赖分组
[tool.uv.group.linting.dependencies]
mypy = ">=1.0"
ruff = ">=0.5"

独立的 uv 配置文件（可与 pyproject.toml 共存）：

index-strategy = "unsafe-best-match"
prerelease = "if-necessary"
resolution = "lowest-direct"
link-mode = "copy"
compile-bytecode = true

[[index]]
name = "private"
url = "https://private.pypi.example.com/simple/"
publish-url = "https://private.pypi.example.com/upload/"

1. --config-file 命令行参数
2. 项目目录的 uv.toml
3. 项目目录的 pyproject.toml [tool.uv]
4. --no-config 可完全禁用配置发现

---

变量	说明
UV_CACHE_DIR	缓存目录路径
UV_NO_CACHE	禁用缓存
UV_CONFIG_FILE	指定配置文件路径
UV_NO_CONFIG	禁用配置文件发现
UV_PROJECT	项目目录路径
UV_PYTHON	Python 解释器路径或版本
UV_MANAGED_PYTHON	强制使用 uv 管理的 Python
UV_NO_MANAGED_PYTHON	禁用 uv 管理的 Python
UV_PYTHON_DOWNLOADS	Python 自动下载策略 (auto/never)
UV_INDEX	额外的包索引 URL
UV_DEFAULT_INDEX	默认包索引 URL (默认 https://pypi.org/simple)
UV_INDEX_STRATEGY	多索引策略 (first-index/unsafe-first-match/unsafe-best-match)
UV_RESOLUTION	解析策略 (highest/lowest/lowest-direct)
UV_PRERELEASE	预发布策略 (disallow/allow/if-necessary/explicit/if-necessary-or-explicit)
UV_FORK_STRATEGY	跨平台分叉策略 (fewest/requires-python)
UV_LINK_MODE	安装链接模式 (clone/copy/hardlink/symlink)
UV_COMPILE_BYTECODE	编译字节码
UV_OFFLINE	禁用网络访问
UV_NATIVE_TLS	使用平台原生 TLS 证书
UV_INSECURE_HOST	允许不安全连接的主机
UV_NO_PROGRESS	隐藏进度条
UV_NO_SYNC	禁用自动同步
UV_LOCKED	锁定模式
UV_FROZEN	冻结模式
UV_ENV_FILE	.env 文件路径
UV_NO_ENV_FILE	禁用 .env 文件
UV_KEYRING_PROVIDER	keyring 认证 (disabled/subprocess)
UV_EXCLUDE_NEWER	排除指定日期之后的包
UV_NO_BUILD	不构建源分发
UV_NO_BINARY	不安装预构建 wheel
UV_PUBLISH_TOKEN	发布 token
UV_PUBLISH_USERNAME	发布用户名
UV_PUBLISH_PASSWORD	发布密码
UV_PUBLISH_INDEX	发布索引名称
UV_PUBLISH_URL	发布 URL
UV_PUBLISH_CHECK_URL	发布检查 URL
UV_VENV_SEED	虚拟环境 seed 包

---

uv 支持在 Python 脚本中内联声明依赖 (PEP 723)，无需创建项目即可运行。

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests>=2.31",
#     "rich>=13.0",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())

运行：

# 自动解析依赖并运行
uv run script.py

# 或显式指定为脚本
uv run --script script.py

# 添加依赖到脚本
uv add requests --script script.py

# 移除脚本依赖
uv remove requests --script script.py

# 锁定脚本依赖
uv lock --script script.py

# 导出脚本依赖
uv export --script script.py

---

uv 支持多包工作区，类似 Rust 的 Cargo workspace 或 JavaScript 的 monorepo。

在根目录 pyproject.toml 中：

[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/experimental"]

或显式列出：

[tool.uv.workspace]
members = ["packages/core", "packages/cli", "packages/api"]

每个成员的 pyproject.toml：

[project]
name = "my-cli"
version = "0.1.0"

[tool.uv.sources]
my-core = {workspace = true}

# 同步所有包
uv sync --all-packages

# 同步指定包
uv sync --package my-cli

# 运行指定包中的命令
uv run --package my-cli python -m my_cli

# 构建所有包
uv build --all-packages

# 构建指定包
uv build --package my-core

# 添加依赖到指定包
uv add requests --package my-cli

# 导出所有包的依赖
uv export --all-packages

---

uv init my-app
cd my-app
uv add requests flask
uv run python hello.py

uv run --with requests --with rich script.py

uv python install 3.12
uv python pin 3.12

uv tool install ruff
uv tool install black
uvx httpx  # 一次性运行 

# 替代 pip install
uv pip install -r requirements.txt

# 替代 pip-compile
uv pip compile requirements.in -o requirements.txt

# 替代 pip-sync
uv pip sync requirements.txt

# 直接用 uv init 创建新项目
uv init --build-backend poetry

# 然后用 uv add 添加依赖
uv add requests --dev

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

COPY . .
RUN uv run python app.py

# GitHub Actions
- name: Install uv
  uses: astral-sh/setup-uv@v4

- name: Install dependencies
  run: uv sync --locked

- name: Run tests
  run: uv run pytest

uv pip install --offline requests
uv sync --offline
uv run --offline python app.py

uv pip install --index https://private.pypi.example.com/simple/ requests

# 或在 pyproject.toml 中配置
# [[tool.uv.index]]
# name = "private"
# url = "https://private.pypi.example.com/simple/"

---

功能	传统工具	uv 命令
创建项目	手动 + setuptools	uv init
安装依赖	pip install	uv add / uv pip install
卸载依赖	pip uninstall	uv remove / uv pip uninstall
锁定依赖	pip-compile	uv lock
同步环境	pip-sync	uv sync / uv pip sync
运行命令	手动激活 venv	uv run
创建 venv	virtualenv / python -m venv	uv venv
Python 版本	pyenv install	uv python install
固定 Python	.python-version (pyenv)	uv python pin
CLI 工具	pipx install	uv tool install / uvx
构建包	python -m build	uv build
发布包	twine upload	uv publish
依赖树	pipdeptree	uv tree / uv pip tree
字节码编译	手动 compileall	--compile-bytecode

---

# 查看可用 Python
uv python list

# 安装需要的版本
uv python install 3.12

# 或指定系统 Python
uv venv -p /usr/bin/python3

# 重建虚拟环境
rm -rf .venv
uv venv
uv sync

# Windows
Remove-Item -Recurse -Force .venv
uv venv
uv sync

# 清理缓存
uv cache clean

# 重新安装
uv sync --reinstall

# 强制升级所有包
uv lock --upgrade

# 升级指定包
uv lock --upgrade-package requests

# 完全重建
rm uv.lock
uv lock

# 降低解析严格度
uv lock --resolution lowest-direct

# 允许预发布
uv lock --prerelease if-necessary

# 排除新版包
uv lock --exclude-newer 2024-01-01

# 使用原生 TLS
uv pip install --native-tls requests

# 允许不安全主机
uv pip install --allow-insecure-host internal.pypi.local requests

# 离线模式
uv pip install --offline requests

# 确保 PATH 包含 uv
$env:Path += ";C:Users86166.localbin"

# PowerShell 执行策略
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

# 使用 uvw (Windows 包装器) 替代 uv
uvw pip install requests