现代Python项目依赖管理工具——uv

发表于 分类于 Valine： 本文字数： 1.6k 阅读时长 ≈ 1 分钟

UV 是一款基于 Rust 编写的高性能 Python 包管理工具，旨在替代传统的工具如 pip、pip-tools 和 venv。UV 的设计目标是简化 Python 项目的依赖管理和虚拟环境配置。

如何安装uv命令？

1）在没有python的环境下，可以使用curl下载安装

curl -LsSf https://gh-proxy.com/https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | sh

2）在有python的环境下，可以通过pip安装

pip install uv

修改Python解释器安装镜像

uv可以在没有python的环境下安装，因为它可以维护python的版本（像anaconda或者nvm一样），默认的镜像服务器从国内访问不稳定，所以可以换成国内镜像地址。

export UV_PYTHON_INSTALL_MIRROR="https://gh-proxy.com/https://github.com/astral-sh/python-build-standalone/releases/download/"

可以加到~/.bashrc

如何初始化一个uv管理的Python项目？

uv init

会在当前文件夹下初始化项目，会自动创建配置文件，包括：

pyproject.toml 现代Python项目通过pyproject.toml管理项目元数据（其中包括项目的依赖包，其替代了传统的requirements.txt管理项目依赖）
.python-version 记录了项目的Python解释器版本，可以通过uv python pin 3.10来修改Python版本（3.10改成希望固定的Python版本）

如何给项目添加依赖包？

给项目添加依赖和安装包是同时进行的，通过

uv add <包名>

这个命令会自动维护pyproject.toml想其中添加包依赖，以及在向虚拟环境安装包的同时更新uv.lock

uv.lock 描述了当前环境具体的完全的包依赖的关系图。

如何给uv指定包的安装源？

和pip一样有时候我们希望把安装源指定成国内镜像或者私有源，可以通过

uv.toml

项目级别私有源配置放在项目根目录（和pyproject.toml同目录）

系统用户级私有源配置放在~/.config/uv/uv.toml

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

如何启动项目

uv run main.py

无论是配置好的旧环境还是纯新的环境，都可以通过这一句启动项目，它会自动检查是否存在正确版本的Python解释器，如果不存在则自动下载安装，自动检查是否创建了虚拟环境如果没有创建则创建并激活，自动检查当前虚拟环境和uv.lock中描述的是否匹配，如果不匹配则自动更新虚拟环境，一切准备好了则启动。

提交必要文件到git

pyproject.toml

.python-version

uv.lock

uv.toml 如果存在项目级的

总结下基于uv的现代Python项目标准工作流

  1. 初始化项目uv init
  2. 固定python版本uv python pin 3.10
  3. 手动编辑pyproject.toml中dependencies以外的字段
  4. 通过uv add [-r]安装包（代替pip install [-r]）
  5. 运行项目uv run main.py

其他一些也许会用到的命令

uv python list 查看当前系统存在的Python版本
uv run python --version 查看当前Python版本
uv pip freeze|grep numpy 查看虚拟环境下某个包版本
uv pip install <包名> 临时安装一个包到虚拟环境下，用于测试
uv sync 把环境恢复到标准的配置