UV 项目管理指南

UV 操作指南

🌎 一. UV 介绍

UV是一个用 Rust 编写的、速度极快的 Python 包和项目管理器。

核心优势：

• ⚡️ 速度提升：依赖安装比pip快 10-100 倍（基于 Rust 并行处理）
• 📦 全流程管理：支持项目初始化、依赖管理、虚拟环境、打包发布等完整生命周期
• 🔄 环境隔离：自动管理虚拟环境，区分dev/prod依赖
• 💾 全局缓存：依赖去重存储，节省磁盘空间
• 🐍 多版本支持：内置 Python 版本管理，可安装/切换不同 Python 解释器
• 🖥️ 跨平台兼容：支持 macOS/Linux/Windows，无额外依赖

🎀 二. 安装 UV

1. Linux/macOS

curl-LsSf https://astral.sh/uv/install.sh|shexportPATH=$PATH:$HOME/.local/bin

2. Windows

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

3. 验证安装

uv --version# 输出格式：uv x.y.z (如 uv 0.1.30)

更多内容，可查看 官方安装文档 。

📙 三. 操作指南

🎯 3.1 命令预览

$ uv --help 一个极速的 Python 包管理器。 用法: uv [OPTIONS] <COMMAND> 命令： auth 管理身份认证 run 运行命令或脚本 init 创建新项目 add 添加依赖到项目 remove 从项目移除依赖 version 读取或更新项目版本 sync 更新项目环境 lock 更新项目的锁文件 export 将项目的锁文件导出为其他格式 tree 展示项目的依赖树 format 格式化项目中的 Python 代码 tool 运行和安装 Python 包提供的工具命令 python 管理 Python 版本和安装 pip 通过 pip 兼容接口管理 Python 包 venv 创建虚拟环境 build 将 Python 包构建为源码发行版和 wheel publish 将发行版上传到索引 cache 管理 uv 的缓存 self 管理 uv 可执行文件 help 显示命令文档

Tip：所有子命令均支持--help查看详细用法，如uv add --help。

🐍 3.2 Py版本管理

# 查看已安装/可安装列表$ uv python list# 安装Python$ uv pythoninstall3.12# 卸载Python$ uv python uninstall3.11# 设置项目默认版本$ uv python pin3.14Updated`.python-version`from`3.12`->`3.14`

🚀 3.3项目管理

# 1️⃣ 创建项目（自动生成 pyproject.toml、README、src 目录等）$ uv init hello_uv# 默认使用系统默认 python$ uv init -p3.12hello_uv# 指定 Python 版本# 2️⃣ 进入项目目录$cdmy_project# 3️⃣ 添加依赖（自动写入 pyproject.toml + 更新 lock）$ uvaddrequests# 运行时依赖$ uvaddruff --dev# 开发依赖（仅 prod 环境不装）# 4️⃣ 同步环境（等同于 pip install -r uv.lock）$ uvsync# 安装全部依赖（包括 dev）$ uvsync--no-dev# 只装运行时依赖（prod 场景）# 5️⃣ 项目验证$ uv version# 项目版本$ uv run python -c"import sys; print(sys.prefix)"# 查看虚拟环境# 6️⃣ 运行代码（自动创建并激活虚拟环境）$ uv run main.py $ uv run main.py --only-dev

🎩 3.4 虚拟环境

# 创建隔离的虚拟环境（替代python -m venv）$ uv venv .venv# 指定Python版本$ uv venv --python3.12.venv# 在虚拟环境中安装种子包$ uv venv .venv --seed

小技巧：激活虚拟环境后，uv会自动使用该环境的解释器，无需手动切换。

📦 3.5 依赖管理

❶基础操作

# 添加生产依赖（写入 pyproject.toml 的 [project.dependencies]）$ uvaddrequests# 自动选择最新兼容版本$ uvadd"requests>=2.31.0"# 指定版本约束# 添加开发依赖（写入 [project.optional-dependencies.dev]）$ uvaddpytest --dev# 仅开发环境使用（测试、格式化等工具）$ uvadd"ruff>=0.1.0"--dev# 代码检查工具# 移除依赖（自动清理关联依赖）$ uv remove requests# 生产依赖$ uv remove pytest --dev# 开发依赖（必须加 --dev）

❷依赖同步

# 根据pyproject.toml和uv.lock安装所有依赖$ uvsync# 首次或变更后执行$ uvsync--check# 仅检查冲突不安装# 仅更新锁文件（不安装，用于CI环境预生成锁文件）$ uv lock# 导出依赖清单（兼容传统 requirements.txt ）$ uvexport>requirements.txt# 生产环境依赖$ uvexport--dev>requirements-dev.txt# 含开发依赖

❸依赖可视化

$ uv tree# 查看依赖树（含子依赖版本）$ uv tree --no-dev# 查看生产依赖关系$ uv tree --only-dev# 查看开发依赖关系$ uv tree --package requests# 查看单个包依赖关系

❹pip包管理

完全可以把uv当作pip加速工具，常用命令如下：

$ uv pip --help Manage Python packages with a pip-compatible interface Usage: uv.exe pip[OPTIONS]<COMMAND>Commands: compile 将"requirements.in"文件编译为"requirements.txt"或"pylock.toml"文件sync将环境与"requirements.txt"或"pylock.toml"文件同步install将包安装到环境中 uninstall 从环境中卸载包 freeze 以依赖清单格式列出环境中已安装的包 list 以表格格式列出环境中已安装的包 show 显示一个或多个已安装包的信息 tree 显示环境的依赖树 check 验证已安装包是否具有兼容的依

# 查看包$ uv pip list $ uv pip tree# 安装包$ uv pipinstallrequests $ uv pipinstallrequests==2.31.0# 导出依赖包$ uv pip freeze>requirements.txt# 导入依赖包$ uv pipinstall-r requirements.txt# 卸载包$ uv pip uninstall requests

🛠️ 3.6 构建与发布

# 构建分发包(生成sdist和wheel包)$ uv build --release# 将构建好的包上传到 PyPI 等索引（需提前配置 .pypirc）$ uv publish --repository pypi

🧰 3.7 辅助工具

# 工具是脱离工程环境独立运行的$ uv toolinstallruff# 代码检查linter$ uv toolinstallblack# 代码formatter$ uv tool list# 查看工具列表$ uv tool uninstall ruff#卸载ruff工具

工具是脱离工程环境独立运行的。

🎓 四. 项目实战

1. 项目初始化

$ uv init fastapi-demo $cdfastapi-demo

2. 添加依赖

$ uvaddfastapi $ uvadduvicorn[standard]

3. 编写代码

# main.pyfromfastapiimportFastAPI app=FastAPI()@app.get("/")defread_root():return{"msg":"Hello, uv & FastAPI"}

4. 运行项目

# 开发模式（自动重载）uv run -- uvicorn main:app --reload# 生产模式uv run -- uvicorn main:app --host0.0.0.0 --port8000

5. 项目结构

fastapi-demo/ ├── pyproject.toml # 项目配置和依赖 ├── uv.lock # 依赖锁定文件 ├── .venv/ # 虚拟环境（自动创建） ├── main.py # 主程序文件 └── README.md

🏆 五. 最佳实践

1. 版本控制：将pyproject.toml和uv.lock纳入版本控制
2. 环境隔离：每个项目使用独立的虚拟环境
3. 依赖锁定：定期运行uv lock更新锁定文件
4. CI/CD 集成：使用uv sync确保环境一致性
5. 多环境管理：为开发、测试、生产环境分别配置依赖

📚 附1：镜像加速

• 通过文件配置（uv或pip）

# uv 的配置文件（如 uv.toml） [tool.uv.sources] name = "tuna" type = "index" url = "https://pypi.tuna.tsinghua.edu.cn/simple"

• 或通过环境变量临时指定：

exportPIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple