🐍 快速定位 / 一眼入口 >>>

• uv init demo
• uv add httpx
• uv run pytest
• uv lock uv sync --locked：/
• uv init --script demo.py uv add --script demo.py httpx uv run demo.py：、、
• uvx ruff check .
• uv tool install ruff
• uv python install 3.12 uv python pin 3.12：、
• uv pip install -r requirements.txt

📥 安装 / 更新入口 >>>

独立安装器（推荐）

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

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

各平台包管理器

Docker

docker run ghcr.io/astral-sh/uv

自更新

• uv self update
• pipx upgrade uv
• pip install --upgrade uv

🚀 最小工作流：新项目从 0 到可运行 >>>

• uv init demo：创建项目
• cd demo
• uv add httpx rich：写入依赖并创建环境
• uv run python main.py：在项目环境内运行
• uv lock uv.lock：更新
• uv sync --locked：按锁文件同步环境

# 初始化项目目录
uv init demo

# 进入项目目录
cd demo

# 添加运行依赖
uv add httpx rich

# 在项目环境内运行入口脚本
uv run python main.py

# 生成或更新锁文件
uv lock

# 按锁文件同步环境
uv sync --locked

Recipe：单文件脚本是 uv 的核心主线

• uv init --script example.py --python 3.12：初始化带 inline metadata 的脚本
• uv add --script example.py requests rich：把依赖写进脚本头部
• uv run example.py：隔离环境运行脚本
• uv lock --script example.py：为脚本生成锁定结果
• #!/usr/bin/env -S uv run --script

# 初始化带 inline metadata 的脚本
uv init --script example.py --python 3.12

# 把依赖写进脚本头部
uv add --script example.py requests rich

# 直接运行脚本
uv run example.py

# 为脚本生成锁定结果
uv lock --script example.py

📦 Recipe：做应用或包，优先走 project workflow >>>

• uv init --app demo：应用项目
• uv init --package demo-lib：库项目
• uv add pydantic：运行依赖
• uv add --dev pytest ruff：开发依赖
• uv run pytest：在项目环境中跑测试
• uv build uv publish：构建与发布

# 初始化包项目
uv init --package demo-lib

# 进入项目目录
cd demo-lib

# 添加运行依赖
uv add pydantic

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

# 在项目环境中运行测试
uv run pytest

# 构建分发包
uv build

Recipe：把命令、测试、临时依赖都收进 uv run

• uv run pytest：运行测试
• uv run ruff check .：运行工具
• uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"
• uv run --python 3.12 python -V：指定解释器
• 带 inline metadata 的脚本会自动隔离运行，不复用项目环境

# 在项目环境中运行测试
uv run pytest

# 在项目环境中执行 ruff
uv run ruff check .

# 临时附带 httpx 依赖并执行一段 Python 代码
uv run --with httpx python -c "import httpx; print(httpx.__version__)"

# 指定解释器版本运行 Python
uv run --python 3.12 python -V

🛠️ Recipe：工具执行分两类，uvx 和 uv tool 不要混 >>>

• uvx ruff check .：临时执行工具
• uv tool install ruff：长期安装工具
• uv tool list：列出现有工具
• uv tool upgrade ruff：升级工具环境
• uv tool uninstall ruff：移除长期安装工具

# 一次性执行工具
uvx pycowsay "hello"

# 长期安装 ruff 到工具环境
uv tool install ruff

# 查看已安装工具
uv tool list

# 升级 ruff 工具环境
uv tool upgrade ruff

Recipe：管理 Python 版本，而不是手动装解释器

• uv python install 3.11 3.12
• uv python list --only-installed
• uv python find 3.12
• uv python pin 3.12
• uv venv --python 3.12

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

# 在当前目录固定 Python 版本
uv python pin 3.12

# 使用指定解释器创建虚拟环境
uv venv --python 3.12

# 确认当前项目实际使用的 Python 版本
uv run python -V

🔁 Recipe：旧项目迁移先稳住，再慢慢切主路径 >>>

• uv venv：创建虚拟环境
• uv pip install -r requirements.txt：先让旧项目跑起来
• uv pip compile requirements.in -o requirements.txt：锁定版本
• uv pip sync requirements.txt：按 requirements 同步环境
• pyproject.toml uv add uv lock

# 创建虚拟环境
uv venv

# 先按 requirements.txt 安装旧项目依赖
uv pip install -r requirements.txt

# 从 requirements.in 解析并锁定版本
uv pip compile requirements.in -o requirements.txt

# 按 requirements.txt 同步环境
uv pip sync requirements.txt

🧩 Recipe：CI / Docker / workspace 以锁文件和缓存为中心 >>>

• astral-sh/setup-uv@v7
• uv sync --locked --all-extras --dev
• UV_CACHE_DIR
• uv cache prune --ci
• uv run --all-packages
• pyproject.toml

# 在 CI 中按锁文件安装依赖和开发环境
uv sync --locked --all-extras --dev

# 执行测试
uv run pytest

# 在 CI 收尾阶段清理缓存
uv cache prune --ci

🔐 Recipe：私有索引和认证别只停留在“记得配” >>>

• uv auth login example.com：把凭据写入 uv credential store
• uv auth token example.com：查看当前服务凭据
• authenticate = "always"
• 403 ignore-error-codes = [403]

# 定义私有包索引
[[tool.uv.index]]

# 给索引起一个名字，供 source 或日志引用
name = "private"

# 私有 simple API 地址
url = "https://packages.example.com/simple"

# 强制先认证，避免匿名请求错误回退到公开索引
authenticate = "always"

# 某些私有源未命中时会返回 403，可显式忽略
ignore-error-codes = [403]

# 登录私有源并写入凭据
uv auth login packages.example.com

# 查看当前记录的 token / 凭据信息
uv auth token packages.example.com

⚡ Quick Ref：高频命令速查 >>>

项目管理

• uv init demo
• uv init --script demo.py --python 3.12
• uv add httpx
• uv add --script demo.py httpx
• uv lock
• uv sync --locked
• uv export -o requirements.txt

运行与测试

• uv run pytest
• uv run demo.py
• uvx ruff check .
• uv tool install ruff
• uv run --python 3.12 python -V

包与依赖

• uv pip install -r requirements.txt
• uv tree
• uv audit
• uv format

Python 版本

• uv python install 3.12
• uv python pin 3.12
• uv python list --only-installed

工具管理

• uv tool list
• uv tool upgrade ruff
• uv tool uninstall ruff

CI / 缓存

• uv sync --locked --all-extras --dev
• uv cache prune --ci

构建与发布

• uv build
• uv publish

⚠️ 常见决策 / 易错点 >>>

• uv run uvx uv tool run
• uvx uv tool run
• uv run script.py .venv
• uv sync --locked
• requirements.txt pyproject.toml
• authenticate = "always"
• uv uv self update

🌐 uv vs 全局 Python：边界与定位 >>>

uv 能替代什么

# uv 管理 Python 版本（不接管系统 python）
uv python install 3.12

# 临时执行一段代码
uv run python -c "print('hello')"

# 临时工具执行
uvx ruff check .

# 长期安装 CLI 工具
uv tool install ruff

为什么不能完全替代全局 Python

• uv 管理的 Python 不会自动成为系统默认解释器
• python
• --default

# 传统方式
python script.py

# uv 方式（更推荐）
uv run script.py

# 典型项目 workflow
uv run python script.py

# 仅限 CI / 容器环境
uv pip install -r requirements.txt --system

适用场景判断