UV 包管理器踩坑

在 Python 的包管理生态中，已有如 pip、pip-tools、poetry、conda 等多种工具，各具特色和功能。

本文将介绍由 Astral 公司推出的包管理工具 uv，它采用 Rust 编写，目标是打造 “Python 版的 Cargo”。

uv 提供了高性能、兼容性强且易于使用的包管理体验，在安装速度、依赖解析和项目管理等方面表现出色，为 Python 开发者带来了全新的选择。

更新：一键换源工具chsrc现已经支持uv及其他三大python包管理工具的镜像修改
前排提示，对付这种比较新的库/框架，在AI辅助写代码时最好打开其“联网搜索“功能
以下任何步骤如果卡壳，请先检查网络问题。尤其是使用curl 或者 wget 安装，最好提前配置好镜像或者配置好系统的科学代理。

和pip的区别，一些要点

• uv和pip的缓存是相互独立的，即使使用了uv pip install 来替换 pip install
• uv自带python版本下载功能，因此无需pyenv等工具
• uv可以接管和自动化虚拟化环境venv(因此可以无视）
• uv有兼容pip等传统及其他包管理器的能力

初始化

首先去安装uv到电脑环境：

• Linux wget -qO- https://astral.sh/uv/install.sh | sh
• Windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

下载源配置

目前换源器如chsrc仅支持pip和conda的换源，uv的镜像配置需要我们手动配置环境变量。具体如下

如果安装一些比较旧的包失败，可能是设定的默认源有问题（例如清华源就没有dataset==2.16.0这个版本）

• Linux

echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"'>> ~/.bashrc
# 或使用阿里源
# echo 'export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple/"' >> ~/.bashrc

执行完成使用bash或者source ~/.bashrc命令让配置 生效

• Windows
  在当前的powershell环境输入
  $env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
  或者直接去系统设置添加个新的环境变量：
  

下包的优先级

uv检查包存在性的顺序如下：

• 如果有设置为default区域的index--url 先在这里查找
• 如果有设置为default区域的extra-index-url 再在这里查找
• 在默认的index-url 系统级mirror源查找
• 在备选的extra-index--url 系统级mirror源查找

注意：使用uv sync或者uv pip install附带--index-strategy unsafe-best-match
`参数（你也可以在pyproject里直接设置） 才能实现上述操作，否则默认只检查同区域设定的的源

如我卡死了torch-cu118的源地址为pytorch.org

[[tool.uv.index]]
name = "torch-cu118"
url = "https://download.pytorch.org/whl/cu118/"
explicit = true

如果uv在给定mirror源找不到包的时候就会失败。

自动处理包冲突和版本要求

uv可以自动处理冲突和版本兼容性，前提是：
（1）这个包在上游mirror存在（例如清华源就不存在dataset==2.16.0的版本，而阿里源则存在）
（2）这个包合当前python环境兼容

常用命令

完成源的配置后（写好pyproject.toml）只需要uv sync （或者新加包使用uv add）。
如果想兼容pip，也可以使用uv pip install命令，参数命令和单独使用pip的时候一致。

另外，平时在运行代码的时候可以直接使用 uv run main.py 这样的命令；如果是通过 uv pip install安装的则和pip包的用法一样，需要先激活虚拟环境，然后再使用python main.py 运行（linux下需要用 python3 main.py）
如果想要运行python脚本时附带现在没有安装的包，则可使用uv run main.py --with numpy

例子：

[project]
name = "uv-playground"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11" # 如果找不到合适或者兼容的包，可以在这里降级
dependencies = [
    "torch>=2.6.0",
    "torchaudio>=2.6.0",
    "torchvision>=0.21.0",
    "datasets==2.16.0",
    "requests",
    "rich>=14.1.0",
]
[tool.uv.sources]
torch = [
  { index = "torch-cu118", marker = "sys_platform != 'linux'"}, # 如果是linux改成 == 'linux'即可 
]

[[tool.uv.index]]
url = "https://mirrors.aliyun.com/pypi/simple"
default = true # 给整个project设定的默认源

[[tool.uv.index]]
name = "torch-cu118"
url = "https://download.pytorch.org/whl/cu118/"
explicit = true # 设置的url是这个包专有的

[[tool.uv.index]]
name = "torchaudio-cu118"
url = "https://download.pytorch.org/whl/cu118/"
explicit = true

[[tool.uv.index]]
name = "torchvision-cu118"
url = "https://download.pytorch.org/whl/cu118/"
explicit = true

参考

https://docs.astral.sh/uv/getting-started/installation/
https://zhuanlan.zhihu.com/p/1930714592423703026
https://blog.csdn.net/2301_80171004/article/details/146218153