Python包管理工具uv的使用

发表于 | 分类于
Python包管理工具uv的使用

前言

一个用 Rust 编写的极速 Python 包和项目管理工具。

  • 🚀 一个工具替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等
  • ⚡️ 比 pip 快 10-100 倍

官方文档

https://uv.doczh.com/

安装

Windows

1
winget install --id=astral-sh.uv  -e

Linux

自动安装

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

手动安装

1
2
3
4
5
# 下载 + 安装到 ~/.local/bin
wget https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-unknown-linux-gnu.tar.gz
tar -xzf uv-x86_64-unknown-linux-gnu.tar.gz
mkdir -p ~/.local/bin
mv uv ~/.local/bin/

无论上面哪种方式，都没有添加环境变量。

添加环境变量

1
2
3
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
uv --version  # 验证

镜像设置

Linux

1
2
echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"'>> ~/.bashrc
source ~/.bashrc

Windows

环境变量

1
2
新建变量名: UV_DEFAULT_INDEX
变量值: https://pypi.tuna.tsinghua.edu.cn/simple

查看生效

1
echo %UV_DEFAULT_INDEX%

项目

在项目中配置(pyproject.toml)

1
2
3
[[tool.uv.index]]
url="https://pypi.tuna.tsinghua.edu.cn/simple"
default=true

安装Python

1
uv python install 3.12

查看已安装的版本

1
uv python list

虚拟环境

进入项目目录

初始化

1
uv init

创建虚拟环境

1
uv venv --python 3.12

也可以

1
uv venv --python 3.12 --seed

其中 --seed 是一个非常有用的选项，它的作用是：

创建虚拟环境时，自动预安装最新版的 pip、setuptools 和 wheel

这相当于传统方式中的：

1
2
3
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel

但 uv 把这个过程一步完成且极速。

激活虚拟环境

1
.venv\Scripts\activate

退出环境

1
deactivate

包管理

列出环境中的所有包：

1
uv pip list

要以 JSON 格式列出包：

1
uv pip list --format json

要以 requirements.txt 格式列出环境中的所有包：

1
uv pip freeze

添加依赖

1
uv add requests

移除依赖：

1
uv remove requests

升级依赖：

1
uv lock --upgrade-package requests

--upgrade-package 标志会尝试将指定的包更新到最新的兼容版本，同时保持锁定文件的其余部分不变。

根据 pyproject.toml 安装所有依赖

1
uv sync

也可以这样安装

安装依赖

1
2
uv pip install -U vllm --pre --extra-index-url https://download.pytorch.org/whl/cu130 --index-strategy unsafe-best-match
uv pip install "vllm[audio]" # For additional audio dependencies

注意：

uv pip install 是“安装包”，uv add 是“声明 + 安装”。
做项目请用 uv add，保持依赖可追踪、可复现！

和下面相同

1
2
uv add -U vllm --pre --index https://download.pytorch.org/whl/cu130 --index-strategy unsafe-best-match
uv add "vllm[audio]"