🚀 UV 使用教程 — Python 包管理基础使用指南

uv 是 Astral 团队用 Rust 写的超高速 Python 包管理器，比 pip 快 10-100 倍。它集成了包管理、虚拟环境、Python 版本管理、项目脚本运行等功能，是 pip + venv + pipx + pyenv 的完美替代品。

一、安装 uv

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

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

# 通过 pip 安装（不推荐，但应急可以用）
pip install uv

# 通过 Homebrew (macOS)
brew install uv

安装后验证：

uv --version
# uv 0.7.x (2026)
💡 安装脚本会自动将 uv 加入 PATH。如果终端找不到命令，重新打开终端或执行 source ~/.bashrc / source ~/.zshenv。

二、新建 / 初始化项目

# 新建项目目录并初始化（推荐）
uv init my_project
cd my_project

# 现有目录中初始化
cd existing_project
uv init

# 指定 Python 版本初始化
uv init my_project --python 3.12

初始化后会生成以下文件：

my_project/
├── pyproject.toml    # 项目配置（核心文件）
├── .python-version   # Python 版本锁定
├── hello.py          # 示例文件
└── README.md

pyproject.toml 结构说明

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[project.scripts]
hello = "hello:main"

三、依赖管理（最常用）

安装依赖

# 安装包（自动写入 pyproject.toml + 更新锁文件）
uv add fastapi uvicorn httpx

# 安装指定版本
uv add "requests>=2.28,<3.0"

# 安装开发依赖（写入 [dependency-groups] dev 组）
uv add ruff pytest --dev

# 安装可选依赖
uv add redis --optional cache

# 从 requirements.txt 导入
uv add -r requirements.txt

# 从其他 pyproject.toml / setup.py 导入
uv add -r setup.py

卸载依赖

# 卸载包（自动移除依赖 + 更新锁文件）
uv remove fastapi

# 卸载开发依赖
uv remove pytest --dev

锁文件 & 环境还原

# 生成 / 更新 uv.lock 锁文件
uv lock

# 按锁文件还原完整环境（部署必备！）
uv sync

# 只安装生产依赖（跳过 dev 组）
uv sync --production

# 安装指定依赖组
uv sync --group test
💡 uv.lock 是跨平台锁文件，记录每个包的精确版本和哈希。提交到 Git，团队协作时保证环境一致。

查看依赖

# 查看项目依赖树
uv tree

# 查看过期依赖
uv pip list --outdated

四、运行命令（无需激活虚拟环境）

uv 自动管理虚拟环境，用 uv run 直接执行，不需要手动 activate。

# 运行 Python 脚本
uv run python main.py

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

# 运行已安装的 CLI 工具
uv run uvicorn main:app --reload
uv run pytest
uv run ruff check .
uv run mypy src/

# 传参（用 -- 分隔）
uv run python main.py -- --debug --port 8080
💡 uv run 首次运行时会自动创建虚拟环境并同步依赖，后续直接使用缓存，速度极快。

五、Python 版本管理（替代 pyenv）

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

# 安装最新稳定版
uv python install

# 为当前项目绑定 Python 版本（写入 .python-version）
uv python pin 3.12

# 查看可用的 Python 版本
uv python list

# 查看已安装的版本
uv python list --only-installed

# 查找 Python 可执行文件路径
uv python find

# 卸载某个版本
uv python uninstall 3.10
💡 uv 可以自动下载并使用你从未安装过的 Python 版本，无需提前手动安装。项目需要 3.11？uv 自己搞定。

六、兼容 pip 模式

如果不想改项目结构，可以把 uv 当作 pip 的高速替代：

# 等价于 pip install（但快 10-100x）
uv pip install fastapi uvicorn

# 安装到指定环境
uv pip install fastapi --python .venv/bin/python

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

# 导出依赖为 requirements.txt（兼容旧工具链）
uv pip freeze > requirements.txt

# 编译 pyproject.toml 为 requirements.txt（含完整依赖树）
uv pip compile pyproject.toml -o requirements.txt

# 编译并包含 dev 依赖
uv pip compile pyproject.toml --extra dev -o requirements-dev.txt

# 查看已安装的包
uv pip list

# 查看某个包的详情
uv pip show fastapi

venv 管理

# 创建虚拟环境
uv venv

# 指定 Python 版本创建
uv venv --python 3.12

# 指定目录名
uv venv .my-venv --python 3.11

七、全局工具（替代 pipx）

# 全局安装 CLI 工具（隔离环境，不污染项目）
uv tool install ruff
uv tool install black
uv tool install pre-commit

# 临时运行一次（不安装，用完即焚）
uvx ruff check .
uvx httpie GET httpbin.org/get
uvx cookiecutter gh:audreyr/cookiecutter-pypackage

# 查看已安装的全局工具
uv tool list

# 升级全局工具
uv tool upgrade ruff

# 卸载全局工具
uv tool uninstall ruff

# 运行全局工具
uv tool run ruff check --fix .
# 或简写
uvx ruff check --fix .
💡 uvx = uv tool run，类似 npx，临时执行一个工具而不用全局安装。

八、代码质量（配合 ruff）

uv 内置推荐搭配 Ruff（同样是 Astral 出品，Rust 实现的超快 linter + formatter）：

# 检查代码问题并自动修复
uv run ruff check --fix .

# 检查但不自动修复（CI 用）
uv run ruff check .

# 格式化代码
uv run ruff format .

# 检查 + 格式化一键搞定
uv run ruff check --fix . && uv run ruff format .

# 在 pyproject.toml 中配置 Ruff

pyproject.toml 中的 Ruff 配置

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]
ignore = ["E501"]

[tool.ruff.format]
quote-style = "double"

九、部署 / 生产常用

# 只安装生产依赖（跳过 dev/test 组）
uv sync --production

# 导出精简版 requirements.txt（用于 Docker 等场景）
uv pip compile pyproject.toml -o requirements.txt --no-annotate

# 在 Docker 中使用（官方推荐镜像）
# Dockerfile 示例：

Dockerfile 示例

FROM python:3.12-slim

# 安装 uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# 复制项目文件
WORKDIR /app
COPY pyproject.toml uv.lock ./

# 安装依赖（仅生产）
RUN uv sync --production --no-dev --no-install-project

# 复制源码
COPY . .

# 运行
CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

十、工作流（Workspaces）— 多项目管理

适用于 monorepo 或微服务场景：

# 根目录 pyproject.toml
[tool.uv.workspace]
members = [
    "packages/*",
    "services/*",
]
# packages/auth/    → 共享认证库
# packages/models/  → 共享数据模型
# services/api/     → API 服务
# services/worker/  → 后台任务

# 同步整个 workspace
uv sync

十一、依赖分组（Dependency Groups）

# 添加不同分组的依赖
uv add pytest --group test
uv add sphinx --group docs
uv add ipython --group dev

# 安装指定分组
uv sync --group test
uv sync --group docs

# 安装多个分组
uv sync --group dev --group test

pyproject.toml 中对应：

[dependency-groups]
dev = ["ruff", "mypy"]
test = ["pytest", "pytest-cov"]
docs = ["sphinx", "sphinx-rtd-theme"]

十二、常用命令速查表

命令说明
uv init初始化项目
uv add <pkg>添加依赖
uv remove <pkg>移除依赖
uv sync同步环境（按锁文件）
uv lock生成/更新锁文件
uv run <cmd>在项目环境中运行命令
uv python install <ver>安装 Python 版本
uv python pin <ver>锁定项目 Python 版本
uv python list查看可用 Python 版本
uv venv创建虚拟环境
uv tool install <pkg>全局安装工具
uvx <cmd>临时运行工具
uv pip install <pkg>pip 兼容模式安装
uv pip freeze导出依赖列表
uv pip compile编译为 requirements.txt
uv tree查看依赖树
uv self update更新 uv 自身

十三、常见问题

Q: uv 和 pip 的区别是什么？

uv 用 Rust 写的，速度快 10-100 倍；自带虚拟环境管理、Python 版本管理、锁文件；一个工具搞定 pip + venv + pipx + pyenv。

Q: 需要手动激活虚拟环境吗？

不需要！uv run 会自动使用项目虚拟环境。如果非要用 source .venv/bin/activate 也行，但没必要。

Q: 已有项目如何迁移到 uv？

cd existing_project
uv init
uv add -r requirements.txt
# 或者直接用 pip 兼容模式
uv pip install -r requirements.txt

Q: uv.lock 和 requirements.txt 有什么区别？

uv.lock 是 uv 的原生锁文件，包含完整依赖树、哈希校验、跨平台信息。requirements.txt 是传统格式。建议提交 uv.lock，仅在需要兼容旧工具链时导出 requirements.txt。

Q: 如何加速 CI/CD？

# GitHub Actions 示例
- uses: astral-sh/setup-uv@v5
- run: uv sync
- run: uv run pytest

uv 的全局缓存 + 锁文件能让 CI 依赖安装从几分钟降到几秒。

参考链接