5月前 / Technical / 40浏览

Python极速环境依赖管理工具uv

在现在AI开发的时代中，python语言逐渐成为主流，但是现在除了公司团队，很少有个人会对python做依赖管理。这就会导致许多人一旦切换环境或者升级版本，很有可能导致原始的项目失效，难以复现。因此，摆脱pip、conda工具，使用uv工具对python的依赖包进行更加细致地管理显得十分重要，uv是基于rust语言编写的极速python极速环境依赖管理器，它相比其他环境具有极快的速度。

1. 为什么要用uv工具，pip直接安装不好吗？

无论是作为一位科研人员还是开发工作者，都习惯原生的pip管理工具，但是由于该工具仅仅对依赖链做版本管理，并不具有整个依赖声明周期的管理功能，换句话说，只是支持“同时安装”，并不支持“同时卸载”，因此可能导致以下问题：
- 在依赖安装的同时，会将其他依赖一并安装，在卸载时只会卸载该依赖，其他剩余依赖会残留，导致后续安装某些包时会存在版本冲突
- 依赖冲突无法解决，在大部分时候，pip安装时并不擅长解决各种不同依赖之前包的冲突问题，容易导致冲突报错
- 环境无记录性，由于只会根据官方pip仓库进行最新依赖包的安装，因此并没有记录当时安装的版本，导致后续执行相同命令安装时，无法感知版本，导致依赖冲突或者不同环境的开发问题

1.1 不适用于uv的场景

因为uv是基于python原生环境进行包的编译和安装，并无法做到像类似于conda一样自动下载编译好的库的功能，因此，在某些场景下，如果某些包午饭正确安装或者编译报错，请尝试使用conda管理

2. uv依赖管理工具概述

官方安装说明：

https://docs.astral.sh/uv/getting-started/installation/

2.0 安装说明

普通安装（基于原生Python）
优点：速度较快，设置环境后会自动安装下载对应版本Python

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

基于已有的Python环境安装（Conda等）

# 使用conda安装cuda环境
conda create -n cuda118_env python=3.10
conda activate cuda118_env
conda install -c nvidia cuda-toolkit=11.8

# 基于conda安装uv
pip install uv

2.1 为什么要使用uv做依赖管理

使用uv进行依赖管理有以下：

可维护性：可以对整个python工程的依赖后续升级和维护进行全声明周期管理
可复现性：由于对环境依赖进行了严格的版本记录，因此可以随时复现当时开发环境
平台无关性：可以在配置中严格定义各种不同环境的定义，一行命令即可适配各种平台开发环境
无残留性：所有的依赖包是作为一个整体，依赖时同时保留，卸载时，全部卸载无残留
极速性：由于uv使用rust改写的依赖管理，在安装依赖检查环境问题时会极快

2.2 uv管理工具常用命令

uv init -p python3.10 快速基于当前目录创建项目，并锁定python3.10为版本
uv venv -p python3.10 快速创建一个基于uv管理的虚拟环境，并锁定python3.10为版本
uv sync 立即根据当前目录下的pyproject.toml 文件对python进行依赖同步或者更新
- 如果经常卡主，可以尝试使用uv sync -v 来实现查看安装编译进度
uv add <package_name> 快速对python环境安装依赖
特殊情况下，想操作pip，可以通过uv pip xxxx命令操作pip，这种情况下是不会同步配置信息到pyproject.toml文件中，因此只是手动修改当前Python环境
如果想操作其他特殊模块，来实现类似于python -m xxxxx等其他模块的功能，则使用uv run xxxx其他模块来替代

2.3 uv配置文件说明

使用uv init等命令后会自动创建以下文件
my_project/
├── .python-version
├── README.md
├── main.py
└── pyproject.toml
其中pyproject.toml为类似于requirements.txt的配置文件，用于限制软件包的版本和依赖关系
执行uv sync 则会自动更新这个配置文件内容的依赖关系，以及下载编译对应的模块

3. 其他配置说明

3.1 镜像加速配置

通过修改项目下的pyproject.toml文件，即可快速添加镜像加速地址

[[tool.uv.index]]
# 使用华为云或者清华镜像作为加速地址
url = "https://repo.huaweicloud.com/repository/pypi/simple"
#url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

3.2 Pytorch镜像管理

由于Pytorch对于不同环境和GPU有着不同的规定，因此需要参考以下步骤配置pytorch环境以实现不同平台和环境自动设置

首先执行 uv add torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126 ，此时会自动将torch等依赖版本添加到pyproject.toml文件中
然后在配置中添加以下配置：

[tool.uv.sources]
torch = [
    { index = "pytorch-cu128", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }
]
torchaudio = [
    { index = "pytorch-cu128", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }
]
torchvision = [
    { index = "pytorch-cu128", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }
]

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