python包管理器uv踩坑
UV 包管理器踩坑
在 Python 的包管理生态中，已有如 pip、pip-tools、poetry、conda 等多种工具，各具特色和功能。
本文将介绍由 Astral 公司推出的包管理工具 uv，它采用 Rust 编写，目标是打造 “Python 版的 Cargo”。
uv 提供了高性能、兼容性强且易于使用的包管理体验，在安装速度、依赖解析和项目管理等方面表现出色，为 Python 开发者带来了全新的选择。
前排提示，对付这种比较新的package，在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 这样的命令
如果想要运行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'"},
][[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