uv 是由 Astral 开发的一个极致性能的 Python 包解析与安装工具，核心用 Rust 编写，目标成为 pip、pip-tools（pip-compile/pip-sync）和 virtualenv 的无缝替代品。它利用高效的依赖解析算法和全局缓存机制，通常可比原生 pip 快 10--100 倍，并对磁盘空间和网络请求进行了高度优化。
基本原理
uv 之前的虚拟环境管理工具通常使用版本记录文档 requirements.txt 文档来管理依赖包，存在的一些问题，包括：
一、只管理直接依赖，不锁定间接依赖
例：只写 requests>=2.25，但 requests 又依赖 urllib3，后者版本浮动可能导致线上/线下行为不一致。
二、无冲突解决记录
出现冲突时，pip 只给出"最终选中的版本"，不解释为什么淘汰其它版本，难以审计
requirements.txt 的理念是可列出包名即可，在管理复杂的今天难以适应各种情况。
uv 的诞生正是可以解决这些问题。uv 在依赖管理上的理念借鉴 Node.js 的包管理机制，主要使用的两个文件来管理依赖包版本：
一、pyproject.toml：
定义项目的主要依赖，包括项目名称、版本、描述、使用的python版本、第三方模块等信息
pyproject.toml：
python
[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:
python
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 实现，依赖网络与缓存策略 |
安装uv
macOS/Linux 推荐方式
python
curl -LsSf https://astral.sh/uv/install.sh | shWindows PowerShell
python
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"通过 pip 安装
python
pip install uv
项目初始化
使用uv管理项目虚拟环境，根据项目的情况可以分为三种类型：
- 创建全新项目时使用uv
- uv替换传统虚拟环境管理的项目
- uv管理的项目使用
新项目使用uv
新建项目
uv 提供了创建全新项目的命令，不仅会创建虚拟环境，而且会创建项目必要的文件。
python
uv init 项目名
UV 会自动创建以下文件：
- .git 创建项目的同时初始化git仓库
- .gitignore 配置好git需要忽略的文件，比如虚拟环境安装目录
- main.py 主文件，示例文件
- pyproject.toml 项目配置文件
- .python-version 项目当前版本文件，记录当前使用的python版本
- README.md 项目说明文档
也可以在创建项目时设置python版本：
python
uv init 项目名 --python 3.12安装依赖
uv 中 即支持传统的pip命令来安装包，也支持uv专用命令add来安装包。
使用uv add 命令安装包
python
uv add 模块功能：向项目添加依赖并更新锁文件
uv add 命令在装包的同时还会更新 pyproject.toml 和 uv.lock 文件，同时保证两个记录文件和虚拟环境中的依赖版本保持一致。
在安装第一个包之后，会在当前项目中创建虚拟环境目录 .venv 和 依赖详细管理文件 uv.lock。
使用 pip 命令安装包
python
uv pip install 模块uv无缝衔接pip命令，可以使用pip命令安装依赖。但是项目配置文件 pyproject.toml 和依赖记录文件 uv.lock中不会写入相关安装记录和依赖。想要将pip安装的包加入uv的管理系统中，有两种方法：
- 在pyproject.toml手动编辑加入模块信息，然后使用uv lock 更新uv.lock文件
- 使用uv add 再次安装，模块信息会自动更新到pyproject.toml
演示：
使用 uv pip 安装之后查看pyproject.toml 文件，发现并没有写入安装的 requests 包，这时需要手动编辑pyproject.toml 然后在 uv lock 才能将requests包加入uv管理机制中。
更新依赖记录文件
更新依赖记录文件 uv.lock
python
uv lock 描述：根据 pyproject.toml 重新生成 uv.lock。
使用 uv add命令会自动更新uv.lock文件，所以不需要手动执行该命令。使用该命令通常是手动编辑了pyproject.toml 之后，需要同步到 uv.lock 中。因为 uv.lock 是记录项目的所有依赖，确保在不同环境下安装的一致性，所以需要更新。
传统项目管理转uv
从一个传统虚拟环境工具管理的项目中转用uv来管理，比如项目之前使用conda来管理虚拟环境，如何专用uv来管理呢？
在已有的项目中使用uv，使用的逻辑是弃用以前的虚拟环境管理工具，使用uv创建新的虚拟环境。
新建虚拟环境
uv venv 创建虚拟环境
python
uv venv <dir>描述：创建或重建指定目录的虚拟环境。如果未指定 dir，默认为当前目录下的 .venv。
演示：
进入一个新的目录中，执行
python
uv venv .venv
安装依赖
使用 pip 命令 导出所有依赖
python
pip freeze > requirements.txt 使用uv add 命令安装所有依赖
python
uv add -r requirements.txt uv项目使用uv
如果拿到的项目本身就是用uv管理，可能是从github下载的项目，这时重建虚拟环境就会非常简单，一条命令就可以了。
安装依赖
使用 uv.lock 更新虚拟环境
python
uv sync功能：根据 uv.lock 同步创建／更新虚拟环境。
在一个使用uv管理的项目中，想要快速的安装好依赖，使用 uv.lock 命令将uv.lock文件中依赖安装到当前环境中
演示：
使用 uv sync 命令创建虚拟环境，会在当目录下创建虚拟环境管理目录 .venv ，然后通过uv.lock文件安装所有依赖。
删除依赖
python
uv remove [OPTIONS] <PACKAGE>功能：从项目移除已声明依赖并更新锁文件。删除安装的包，并更新锁文件
运行代码
在uv管理中，运行python代码有两种方式：
一、传统方法
首先激活虚拟环境
python
source .venv/bin/activate然后执行python代码
python
python main.py演示：
二、uv 方法
python
uv run 功能：在 uv 管理的环境中运行指定命令或 Python 脚本。
使用 uv run 命令直接执行python代码
python
uv run main.py使用 uv run 文件名，在不需要激活虚拟环境的前提下就能执行代码，uv命令会自动将python代码放在配置好的虚拟环境中执行，节省了步骤。
演示：
设置pypi源
python的依赖安装时通常都需要使用国内源，速度远远高于国外的源。uv中使用国内源的方法有三种。
方法一、指定源安装包（开发临时）
在 uv add 时添加pypi的源
bash
uv add requests --default-index https://pypi.tuna.tsinghua.edu.cn/simple好处是比较灵活，每次安装都可以使用不同的源，缺点是每次都需要添加一串常常的后缀
方法二：环境变量（临时或全局）
在环境变量中设置如下的命令
bash
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"适用于一次性命令或写入 .bashrc / .zshrc 实现全局生效。
方法三：项目级配置（推荐用于团队协作）
在项目的 pyproject.toml 中添加：
toml
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true此配置优先级高于环境变量和全局配置。
更换python版本
python开发过程中选择不同的版本也很重要，uv对python版本的管理也很灵活，可以列出所有python版本，下载指定版本，使用指定版本。
列出所有版本
python
uv python list 包括当前本地安装过的版本和未安装的版本。
下载指定版本解释器
uv python install 命令可以安装指定版本的python解释器
bash
uv python install 版本号安装python 3.12版本
使用指定版本解释器
项目中指定 Python 版本
下载指定的版本之后还需要将项目切换到指定版本，切换到指定版本的方法有多种。
方法一：在创建项目时指定版本
python
uv init my-project --python 3.12方法二：在现有项目中设置版本
python
echo "3.12" > .python-version方法三：在 pyproject.toml 中指定
编辑 pyproject.toml 文件,在 pyproject.toml 中配置：
python
[project]
requires-python = ">=3.12,<3.13"方法四：使用 uv python pin 命令
python
uv python pin python版本Python 版本请求写入 .python-version 或 .python-versions，实现"锁定"效果
切换版本之后记得需要重新安装依赖，那么安装依赖的命令是？
总结
从我接触uv工具来看，uv至少有三个优点相较于传统requirements.txt依赖管理的好处：
- 模块的依赖问题有效的解决了
- 项目重建时安装过程很丝滑，不会出现依赖的依赖冲突，依赖升级等导致的安装失败
- 不需要进入虚拟环境就能执行代码，减少一步操作也是优点
本文只描述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的版本 |
参考:
https://www.cnblogs.com/luckAI/p/18919512