一、 uv简介
相比 pip 与 venv 的使用，uv确实有一定的学习门槛。熟悉前端nodejs的同学应该会比较熟悉。
在介绍uv之前，先简单介绍一下python依赖等概念。
模块管理、模块依赖管理
模块是指虚拟环境中安装的第三方模块及其版本。大多数项目对第三方库的版本都是有特定要求，如果对旧版本的项目使用新版本的依赖，可能会报很奇怪的错误。
当安装第三方模块时，第三方模块可能会安装自己依赖的模块。当安装两个以上模块时，就可能出现第三方模块的依赖出现冲突。这种情况一般是依赖的版本冲突。这种就叫做相关性依赖
pip 的不足
pip 是 python 内置的依赖管理工具，它应该会是python开发者最常用的包管理命令。
而pip最大的不足在于 第三方模块的相关性依赖管理 的能力不足。尤其是在删除第三方模块是的依赖解析。
举个例子：安装python包A时，A需要先安装B，C。而在删除A时，pip并不知道A和B，C之间的关系，所以只会删除A，而不会处理B，C。
uv的管理方式
uv的管理方式类似于poetry，它依靠自动生成的pyproject.toml和uv.lock文件管理依赖。
pyproject.toml：定义项目的主要依赖，包括项目名称、版本、描述、支持的Python版本等信息uv.lock：记录项目的所有依赖，包括依赖的依赖，且跨平台，确保在不同环境下安装的一致性。这个文件不要手动编辑。
运行初始化命令uv init，会自动创建pyproject.toml文件。需要注意的是，虚拟环境目录.venv和lock文件uv.lock此时不会创建。
运行uv add <package>， 会做三件事：
- 将你指定的package添加到pyproject.toml文件的
[dependencies]下面； - 同时修改
uv.lock； - 根据
uv.lock，更新虚拟环境。
所以基本上uv的使用过程就是：使用命令修改pyproject.toml，uv自动根据pyproject.toml修改uv.lock，uv根据uv.lock管理依赖。
二、 uv教程
（一）安装与环境配置
1. 全平台一键安装（推荐方式）
BASH# 使用Astral官方安装脚本
# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"2. pip 安装
# 将uv安装到当前python环境
pip install uv输出示例：
✅ 已安装uv v0.18.0到 /home/user/.local/bin
运行 `uv --version` 验证安装2. 环境变量配置（可选）
BASH# 将uv加入PATH（针对zsh/bash）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc3. 版本升级与维护
BASH# 检查更新通道
uv self upgrade --channel=nightly # 尝鲜版
uv self upgrade --channel=stable # 稳定版4. uv移除
# 清楚缓存和工具（可选）
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"
# 移除
# On macOS and Linux.
rm ~/.local/bin/uv ~/.local/bin/uvx
#On windows
rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe（二）uv核心语法详解
1. 包管理基础命令
| 命令格式 | 作用描述 | 示例场景 |
|---|---|---|
| uv init | 初始化，创建pyproject.toml | |
| uv add |
修改pyproject.toml和uv.lock，安装 |
uv add transformer |
| uv sync | 根据uv.lock，配置环境，安装uv.lock中所有的依赖 | 拿到一个开源项目，按照开源项目配置的环境，配置一个一模一样的本地环境 |
| uv lock | 创建uv.lock（如果没有），根据pyproject.toml更新uv.lock | |
| uv export | 把uv.lock中的配置导出为requirements.txt |
高频参数解析：
- —no-deps: 跳过依赖安装（仅安装主包）
- —index-url: 指定私有PyPI源地址
- —timeout: 设置超时时间（默认120秒）
- —pre: 允许安装预发布版本
2. 虚拟环境管理
BASH# 创建并激活虚拟环境（兼容venv语法）
uv venv .venv # 创建环境目录
source .venv/bin/activate # 激活环境（Linux/macOS）
.venv\Scripts\activate # 激活环境（Windows）
# 导出环境依赖
uv pip freeze > requirements.txt # 生成精确版本列表
# 跨平台环境复制
uv pip sync requirements.txt --python=3.11 # 强制指定Python版本3. 高级依赖控制
BASH# 版本锁定与更新
uv lock # 生成uv.lock文件（替代poetry.lock）
uv update # 更新所有依赖到最新兼容版本
uv update <package> # 指定包更新
# 依赖树分析（可视化冲突解决）
uv tree --format=graph # 生成依赖关系图（需安装graphviz）
uv dep conflicts # 快速定位版本冲突（三）性能调优与最佳实践
1. 缓存优化技巧
BASH# 查看缓存统计
uv cache info
# 清理过期缓存（30天前）
uv cache prune --keep-within 30d
# 指定自定义缓存路径
export UV_CACHE_DIR=/mnt/ssd_cache/uv
uv install --cache-dir /mnt/ssd_cache/uv2. 多线程加速
BASH# 根据CPU核心数自动分配线程（实测8核提升3倍速度）
uv install --threads $(nproc)
# 限制最大线程数（避免资源争抢）
uv install --threads 43. 依赖安装策略对比
| 策略 | 命令参数 | 适用场景 |
|---|---|---|
| 极速模式 | —strategy=unpack | 跳过完整性校验（仅限可信源） |
| 安全模式 | —strategy=copy | 企业内网严格审计环境 |
| 空间优化 | —strategy=link | 硬盘空间有限时使用符号链接 |
（四）常见问题排查指南
问题1：依赖版本冲突
BASH# 步骤1：生成冲突报告
uv dep conflicts --markdown > conflicts.md
# 步骤2：手动指定版本
uv install "pandas==2.2.0" "numpy<1.25"
# 步骤3：强制覆盖安装（慎用）
uv install --resolution=highest问题2：私有仓库认证失败
TOML# 在项目根目录创建 uv.toml
[auth.private-repo]
type = "basic"
username = "$UV_USER" # 从环境变量读取
password = "$UV_TOKEN"问题3：跨平台环境不一致
BASH# 生成平台锁定文件
uv lock --platform linux-x86_64 --platform macos-arm64
# 安装时指定目标平台
uv install --target-platform win-amd64
