uv 现代化的虚拟环境管理工具

由 Astral 开发的一个极致性能的 Python 包解析与安装工具，核心用 Rust 编写，目标成为 pip、pip-tools（pip-compile/pip-sync）和 virtualenv 的无缝替代品。它利用高效的依赖解析算法和全局缓存机制，通常可比原生 pip 快 10–100 倍，并对磁盘空间和网络请求进行了高度优化。

1|0基本原理

uv 之前的虚拟环境管理工具通常使用版本记录文档 requirements.txt 文档来管理依赖包，存在的一些问题，包括：

一、只管理直接依赖，不锁定间接依赖

例：只写 requests>=2.25，但 requests 又依赖 urllib3，后者版本浮动可能导致线上/线下行为不一致。

二、无冲突解决记录

出现冲突时，pip 只给出“最终选中的版本”，不解释为什么淘汰其它版本，难以审计

requirements.txt 的理念是可列出包名即可，在管理复杂的今天难以适应各种情况。

uv 的诞生正是可以解决这些问题。uv 在依赖管理上的理念借鉴 Node.js 的包管理机制，主要使用的两个文件来管理依赖包版本：

一、pyproject.toml：

定义项目的主要依赖，包括项目名称、版本、描述、使用的python版本、第三方模块等信息

pyproject.toml：

[project] name = "strem-demo" version = "0.1.0" description = "视频流测试项目" readme = "README.md" requires-python = ">=3.10" dependencies = [ "flask>=3.1.1", "requests>=2.32.4", ]

二、uv.lock：

记录项目的所有依赖，包括依赖的依赖，安装包的hash校验，确保在不同环境下安装的一致性。这个文件由 uv 自动管理，不要手动编辑。

uv.lock:

version = 1 revision = 2 requires-python = ">=3.10" [[package]] name = "strem-demo" version = "0.1.0" source = { virtual = "." } dependencies = [ { name = "flask" }, { name = "requests" }, ] [[package]] name = "flask" version = "3.1.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "blinker" }, { name = "click" }, { name = "itsdangerous" }, { name = "jinja2" }, { name = "markupsafe" }, { name = "werkzeug" }, ] sdist = { url = "https://files.pythonhosted.org/packages/c0/de/e47735752347f4128bcf354e0da07ef311a78244eba9e3dc1d4a5ab21a98/flask-3.1.1.tar.gz", hash = "sha256:284c7b8f2f58cb737f0cf1c30fd7eaf0ccfcde196099d24ecede3fc2005aa59e", size = 753440, upload-time = "2025-05-13T15:01:17.447Z" } wheels = [ { url = "https://files.pythonhosted.org/packages/3d/68/9d4508e893976286d2ead7f8f571314af6c2037af34853a30fd769c02e9d/flask-3.1.1-py3-none-any.whl", hash = "sha256:07aae2bb5eaf77993ef57e357491839f5fd9f4dc281593a81a9e4d79a24f295c", size = 103305, upload-time = "2025-05-13T15:01:15.591Z" }, ] [[package]] name = "requests" version = "2.32.4" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "certifi" }, { name = "charset-normalizer" }, { name = "idna" }, { name = "urllib3" }, ] sdist = { url = "https://files.pythonhosted.org/packages/e1/0a/929373653770d8a0d7ea76c37de6e41f11eb07559b103b1c02cafb3f7cf8/requests-2.32.4.tar.gz", hash = "sha256:27d0316682c8a29834d3264820024b62a36942083d52caf2f14c0591336d3422", size = 135258, upload-time = "2025-06-09T16:43:07.34Z" } wheels = [ { url = "https://files.pythonhosted.org/packages/7c/e4/56027c4a6b4ae70ca9de302488c5ca95ad4a39e190093d6c1a8ace08341b/requests-2.32.4-py3-none-any.whl", hash = "sha256:27babd3cda2a6d50b30443204ee89830707d396671944c998b5975b031ac2b2c", size = 64847, upload-time = "2025-06-09T16:43:05.728Z" }, ]

uv.lock 文件记录了：

• 所有依赖的精确版本号
• 依赖关系图谱
• 跨平台的哈希校验

这确保了团队成员和部署环境中的依赖版本完全一致

UV 和 npm 对比

维度	uv（Python）	npm（Node.js）
配置中心	pyproject.toml + uv.lock	package.json + package-lock.json
安装命令	uv add, uv sync	npm install
包来源	PyPI、Git、本地路径	npm registry、Git、本地路径
安装模式	项目模式 vs 独立包模式	统一从 registry 或 lock 文件安装
环境管理	自动创建 .venv 虚拟环境	本地 node_modules + 可选 .nvmrc
性能实现	Rust 实现，10~100 倍性能提升	JavaScript 实现，依赖网络与缓存策略

2|0安装uv

macOS/Linux 推荐方式

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

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

通过 pip 安装

pip install uv

3|0项目初始化

使用uv管理项目虚拟环境，根据项目的情况可以分为三种类型：

1. 创建全新项目时使用uv
2. uv替换传统虚拟环境管理的项目
3. uv管理的项目使用

3|1新项目使用uv

新建项目

uv 提供了创建全新项目的命令，不仅会创建虚拟环境，而且会创建项目必要的文件。

uv init 项目名

UV 会自动创建以下文件：

• .git 创建项目的同时初始化git仓库
• .gitignore 配置好git需要忽略的文件，比如虚拟环境安装目录
• main.py 主文件，示例文件
• pyproject.toml 项目配置文件
• .python-version 项目当前版本文件，记录当前使用的python版本
• README.md 项目说明文档

也可以在创建项目时设置python版本：

uv init 项目名 --python 3.12

安装依赖

uv 中 即支持传统的pip命令来安装包，也支持uv专用命令add来安装包。

使用uv add 命令安装包

uv add 模块

功能：向项目添加依赖并更新锁文件

uv add 命令在装包的同时还会更新 pyproject.toml 和 uv.lock 文件，同时保证两个记录文件和虚拟环境中的依赖版本保持一致。

在安装第一个包之后，会在当前项目中创建虚拟环境目录 .venv 和 依赖详细管理文件 uv.lock。

使用 pip 命令安装包

uv pip install 模块

uv无缝衔接pip命令，可以使用pip命令安装依赖。但是项目配置文件 pyproject.toml 和依赖记录文件 uv.lock中不会写入相关安装记录和依赖。想要将pip安装的包加入uv的管理系统中，有两种方法：

1. 在pyproject.toml手动编辑加入模块信息，然后使用uv lock 更新uv.lock文件
2. 使用uv add 再次安装，模块信息会自动更新到pyproject.toml

演示：

使用 uv pip 安装之后查看pyproject.toml 文件，发现并没有写入安装的 requests 包，这时需要手动编辑pyproject.toml 然后在 uv lock 才能将requests包加入uv管理机制中。

更新依赖记录文件

更新依赖记录文件 uv.lock

uv lock

描述：根据 pyproject.toml 重新生成 uv.lock。

使用 uv add命令会自动更新uv.lock文件，所以不需要手动执行该命令。使用该命令通常是手动编辑了pyproject.toml 之后，需要同步到 uv.lock 中。因为 uv.lock 是记录项目的所有依赖，确保在不同环境下安装的一致性，所以需要更新。

3|2传统项目管理转uv

从一个传统虚拟环境工具管理的项目中转用uv来管理，比如项目之前使用conda来管理虚拟环境，如何专用uv来管理呢？

在已有的项目中使用uv，使用的逻辑是弃用以前的虚拟环境管理工具，使用uv创建新的虚拟环境。

新建虚拟环境

uv venv 创建虚拟环境

uv venv <dir>

描述：创建或重建指定目录的虚拟环境。如果未指定 dir，默认为当前目录下的 .venv。

演示：

进入一个新的目录中，执行

uv venv .venv

安装依赖

使用 pip 命令 导出所有依赖

pip freeze > requirements.txt

使用uv add 命令安装所有依赖

uv add -r requirements.txt

3|3uv项目使用uv

如果拿到的项目本身就是用uv管理，可能是从github下载的项目，这时重建虚拟环境就会非常简单，一条命令就可以了。

安装依赖

使用 uv.lock 更新虚拟环境

uv sync

功能：根据 uv.lock 同步创建／更新虚拟环境。

在一个使用uv管理的项目中，想要快速的安装好依赖，使用 uv.lock 命令将uv.lock文件中依赖安装到当前环境中

演示：

使用 uv sync 命令创建虚拟环境，会在当目录下创建虚拟环境管理目录 .venv ，然后通过uv.lock文件安装所有依赖。

删除依赖

uv remove [OPTIONS] <PACKAGE>

功能：从项目移除已声明依赖并更新锁文件。删除安装的包，并更新锁文件

4|0运行代码

在uv管理中，运行python代码有两种方式：

1. 先激活虚拟环境，然后python main.py
2. 使用 uv run main.py ，自动在虚拟环境中执行代码

一、传统方法

首先激活虚拟环境

source .venv/bin/activate

然后执行python代码

python main.py

演示：

二、uv 方法

uv run

功能：在 uv 管理的环境中运行指定命令或 Python 脚本。

使用 uv run 命令直接执行python代码

uv run main.py

使用 uv run 文件名，在不需要激活虚拟环境的前提下就能执行代码，uv命令会自动将python代码放在配置好的虚拟环境中执行，节省了步骤。

演示：

5|0设置pypi源

python的依赖安装时通常都需要使用国内源，速度远远高于国外的源。uv中使用国内源的方法有三种。

方法一、指定源安装包（开发临时）

在 uv add 时添加pypi的源

uv add requests --default-index https://pypi.tuna.tsinghua.edu.cn/simple

好处是比较灵活，每次安装都可以使用不同的源，缺点是每次都需要添加一串常常的后缀

方法二：环境变量（临时或全局）

在环境变量中设置如下的命令

export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"

适用于一次性命令或写入 .bashrc / .zshrc 实现全局生效。

方法三：项目级配置（推荐用于团队协作）

在项目的 pyproject.toml 中添加：

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

此配置优先级高于环境变量和全局配置。

6|0更换python版本

python开发过程中选择不同的版本也很重要，uv对python版本的管理也很灵活，可以列出所有python版本，下载指定版本，使用指定版本。

6|1列出所有版本

uv python list

包括当前本地安装过的版本和未安装的版本。

6|2下载指定版本解释器

uv python install 命令可以安装指定版本的python解释器

uv python install 版本号

安装python 3.12版本

6|3使用指定版本解释器

项目中指定 Python 版本

下载指定的版本之后还需要将项目切换到指定版本，切换到指定版本的方法有多种。

方法一：在创建项目时指定版本

uv init my-project --python 3.12

方法二：在现有项目中设置版本

echo "3.12" > .python-version

方法三：在 pyproject.toml 中指定

编辑 pyproject.toml 文件,在 pyproject.toml 中配置：

[project] requires-python = ">=3.12,<3.13"

方法四：使用 uv python pin 命令

uv python pin python版本

Python 版本请求写入 .python-version 或 .python-versions，实现“锁定”效果

切换版本之后记得需要重新安装依赖，那么安装依赖的命令是？

7|0总结

从我接触uv工具来看，uv至少有三个优点相较于传统requirements.txt依赖管理的好处：

1. 模块的依赖问题有效的解决了
2. 项目重建时安装过程很丝滑，不会出现依赖的依赖冲突，依赖升级等导致的安装失败
3. 不需要进入虚拟环境就能执行代码，减少一步操作也是优点

本文只描述uv使用的初级入门指南，uv的功能较为强大，远不止如此。uv的愿景是打造一个python项目开发一体化的解决方案，不仅包括虚拟环境管理，还有项目管理、配置文件统一管理、工具管理、代码检测等。

高频命令：

命令	功能	特点
uv add 模块	安装包和模块	同步更新依赖管理文件
uv pip install 模块	安装包和模块	不更新依赖管理文件
uv lock	根据pyproject.toml创建lock文件	手动修改pyproject.toml需要的操作
uv sync	根据uv.lock安装依赖	适用于项目环境重建
uv run demo.py	执行代码	不需要启动虚拟环境
uv python demo.py	执行代码	需要手动开启虚拟环境
uv venv dir	创建虚拟环境	手动创建虚拟环境
uv pip list	列出所有的python版本	包括当前环境有的和没有的
uv pip install 3.12	安装指定python版本	下载安装指定python版本
uv python pin python版本	指定项目使用python版本	更新python的版本