新一代Python管理UV完全使用指南｜附实际体验与效果对比
简介
uv是新一代的Python项目管理工具，具备开发一个完整项目的所有功能点：
| 功能点 | 描述 |
|---|---|
| 包管理 | 完全替代pip的功能，支持包的安装、升级、卸载等操作 |
| 虚拟环境管理 | 内置虚拟环境创建和管理，无需额外安装virtualenv或venv |
| 依赖解析与锁定 | 提供智能依赖解析算法并生成锁定文件(uv.lock) |
| Python版本管理 | 能够自动安装和管理不同版本的Python解释器 |
| 项目初始化 | 通过uv init快速创建新项目并生成标准结构 |
| 脚本运行 | 支持在虚拟环境中直接运行脚本而无需手动激活环境 |
| 包发布 | 内置支持将项目打包并发布到PyPI等仓库 |
安装
# On Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh# On macOS
brew install uv# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# With pip.
pip install uv
用法
1. 命令简介
uv包含以下命令，前几个是比较常用的。
| 命令 | 描述 |
|---|---|
run | 运行命令或脚本 |
init | 创建一个新项目 |
add | 向项目中添加依赖项 |
remove | 从项目中移除依赖项 |
sync | 更新项目的环境 |
lock | 更新项目的锁定文件 |
export | 将项目的锁定文件导出为其他格式 |
tree | 显示项目的依赖树 |
tool | 运行和安装由 Python 包提供的命令 |
python | 管理 Python 版本和安装 |
pip | 使用兼容 pip 的接口管理 Python 包 |
venv | 创建虚拟环境 |
build | 将 Python 包构建为源代码分发包和 wheels |
publish | 将分发包上传到索引 |
cache | 管理 uv 的缓存 |
self | 管理 uv 可执行文件 |
version | 显示 uv 的版本 |
generate-shell-completion | 生成 shell 自动补全脚本 |
help | 显示某个命令的文档 |
2. 文件结构
首先执行以下命令初始化一个项目：
uv init test-uv
项目结构：
test-uv├─ .git├─.gitignore├─.python-version├─README.md├─main.py├─pyproject.toml
可以看到项目中除了Python相关的脚本外，还生成了git，用于版本管理。
# pyproject.toml
[project]
name = "test-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = []
pyproject.toml是项目配置信息，类似于JS中的package.json。
# python-version
3.10
.python-version记录了当前项目使用的Python环境版本，可以自行编辑修改。
3. 运行脚本
uv中执行脚本的启动命令为：
# 与JS中`npm run dev`类似
uv run xxx
uv run 的执行逻辑为：
- 检查当前目录中是否存在
.venv目录，若不存在则创建新环境 - 验证环境是否包含脚本所需依赖，如果缺失依赖则自动安装
- 在当前的虚拟环境中执行命令，不会与其他环境产生冲突
以下是uv启动命令与常规Python启动命令的对比：
| 执行命令 | 环境处理 |
|---|---|
uv run xxx | 自动关联虚拟环境： - 优先使用当前目录下的 .venv- 若不存在会自动创建 - 无需手动激活/停用 |
python xxx.py | 依赖当前Shell环境： - 需手动激活虚拟环境 |
4. 管理依赖
4.1 add
用于安装包并自动更新项目配置文件（pyproject.toml）和锁定文件（uv.lock）
# 安装最新版包
uv add requests# 安装指定版本
uv add "flask>=2.0.0"uv add git+https://github.com/psf/requests.gituv add 可以理解为 uv pip install的增强版，底层同样是利用了pip进行安装，但是uv add额外增加了更新项目配置文件的功能
4.2 remove
用于卸载包并更新项目配置
# 同步所有依赖（包括dev）
uv sync# 仅同步生产依赖
uv sync --production# 同步并清理多余包
uv sync --clean
4.3 sync
根据锁定文件精确还原依赖环境
# 同步所有依赖（包括dev）
uv sync# 仅同步生产依赖
uv sync --production# 同步并清理多余包
uv sync --clean
4.4 lock
创建/更新 uv.lock文件，用于跨平台精确版本记录
# 生成新锁定文件
uv lock# 检查更新但不写入（dry-run）
uv lock --check# 强制重新解析
uv lock --update
4.5 tree
用于可视化展示依赖关系
# 显示完整依赖树
uv tree# 仅显示指定包的依赖路径
uv tree flask# 反向追溯依赖（谁依赖了这个包）
uv tree --reverse sqlalchemy# 输出为JSON格式
uv tree --format json
5. 管理Python环境
基本命令：
uv python [OPTIONS] <COMMAND>
可选参数如下：
| 命令 | 描述 |
|---|---|
list | 列出可用的Python安装版本 |
install | 下载并安装Python版本 |
find | 显示当前Python安装位置 |
pin | 固定使用特定Python版本 |
dir | 显示uv Python安装目录 |
uninstall | 卸载Python版本 |
uv python list
cpython-3.14.0a5+freethreaded-macos-aarch64-none <download available>
cpython-3.14.0a5-macos-aarch64-none <download available>
cpython-3.13.2+freethreaded-macos-aarch64-none <download available>
cpython-3.13.2-macos-aarch64-none /opt/homebrew/opt/python@3.13/bin/python3.13 -> ../Frameworks/Python.framework/Versions/3.13/bin/python3.13
cpython-3.13.2-macos-aarch64-none <download available>
cpython-3.12.9-macos-aarch64-none /opt/homebrew/opt/python@3.12/bin/python3.12 -> ../Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.9-macos-aarch64-none <download available>
cpython-3.11.11-macos-aarch64-none /opt/homebrew/opt/python@3.11/bin/python3.11 -> ../Frameworks/Python.framework/Versions/3.11/bin/python3.11
cpython-3.11.11-macos-aarch64-none <download available>
cpython-3.10.16-macos-aarch64-none /Users/.local/share/uv/python/cpython-3.10.16-macos-aarch64-none/bin/python3.10
cpython-3.9.21-macos-aarch64-none /opt/homebrew/opt/python@3.9/bin/python3.9 -> ../Frameworks/Python.framework/Versions/3.9/bin/python3.9
cpython-3.9.21-macos-aarch64-none <download available>
cpython-3.9.12-macos-aarch64-none /Users/opt/anaconda3/bin/python3.9
cpython-3.9.12-macos-aarch64-none /Users/opt/anaconda3/bin/python3 -> python3.9
cpython-3.9.12-macos-aarch64-none /Users/opt/anaconda3/bin/python -> python3.9
cpython-3.9.6-macos-aarch64-none /Library/Developer/CommandLineTools/usr/bin/python3 -> ../../Library/Frameworks/Python3.framework/Versions/3.9/bin/python3
cpython-3.8.20-macos-aarch64-none <download available>
pypy-3.11.11-macos-aarch64-none <download available>
pypy-3.10.16-macos-aarch64-none <download available>
pypy-3.9.19-macos-aarch64-none <download available>
pypy-3.8.16-macos-aarch64-none <download available>
python环境并不完全都是新的，会根据本地已有的环境添加软连接，如brew安装的python3.11～python3.13和conda的python3.9都被添加软连接进行复用。
而<download available>则表示当前本地环境没有，uv可以下载的版本。
uv python install python3.6
error: No download found for request: cpython-3.6-macos-aarch64-none
这是因为上面的list中不支持3.6
uv python install python3.8
Installed Python 3.8.20 in 3.98s
安装Python3.8就可以了
执行以下命令可以查看uv中的Python环境：
ll ~/.local/share/uv/python/
.gitignore
.lock
.temp
cpython-3.10.16-macos-aarch64-none
cpython-3.8.20-macos-aarch64-none
显示已安装了2个Python环境：
- 3.10是项目的
.python-version中指定的，在项目初始化或者创建venv环境的适合就会创建该Python环境； - 3.8是前面通过
uv python install python3.8进行安装的。
6. 下载速度对比
安装一个torch进行对比，执行以下命令：
time pip install torch
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Collecting torchDownloading https://pypi.tuna.tsinghua.edu.cn/packages/b3/17/41f681b87290a1d2f1394f943e470f8b0b3c2987b7df8dc078d8831fce5b/torch-2.6.0-cp39-none-macosx_11_0_arm64.whl (66.5 MB)|████████████████████████████████| 66.5 MB 41.9 MB/s
Requirement already satisfied: jinja2 in /Users/wuzisheng/opt/anaconda3/lib/python3.9/site-packages (from torch) (3.1.6)
Requirement already satisfied: typing-extensions>=4.10.0 in /Users/wuzisheng/opt/anaconda3/lib/python3.9/site-packages (from torch) (4.12.2)
Requirement already satisfied: filelock in /Users/wuzisheng/opt/anaconda3/lib/python3.9/site-packages (from torch) (3.6.0)
Collecting sympy==1.13.1Downloading https://pypi.tuna.tsinghua.edu.cn/packages/b2/fe/81695a1aa331a842b582453b605175f419fe8540355886031328089d840a/sympy-1.13.1-py3-none-any.whl (6.2 MB)|████████████████████████████████| 6.2 MB 30.9 MB/s
Requirement already satisfied: fsspec in /Users/wuzisheng/opt/anaconda3/lib/python3.9/site-packages (from torch) (2025.3.1)
Requirement already satisfied: networkx in /Users/wuzisheng/opt/anaconda3/lib/python3.9/site-packages (from torch) (2.7.1)
Requirement already satisfied: mpmath<1.4,>=1.1.0 in /Users/wuzisheng/opt/anaconda3/lib/python3.9/site-packages (from sympy==1.13.1->torch) (1.2.1)
Requirement already satisfied: MarkupSafe>=2.0 in /Users/wuzisheng/opt/anaconda3/lib/python3.9/site-packages (from jinja2->torch) (2.0.1)
Installing collected packages: sympy, torchAttempting uninstall: sympyFound existing installation: sympy 1.10.1Uninstalling sympy-1.10.1:Successfully uninstalled sympy-1.10.1
Successfully installed sympy-1.13.1 torch-2.6.0
pip install torch 7.38s user 3.69s system 51% cpu 21.551 total
总共耗时21秒。
执行以下命令使用uv进行下载
time uv pip install torch --python .venv/bin/python
Resolved 9 packages in 2.68s
Prepared 9 packages in 7.64s
Installed 9 packages in 199ms+ filelock==3.18.0+ fsspec==2025.3.2+ jinja2==3.1.6+ markupsafe==3.0.2+ mpmath==1.3.0+ networkx==3.4.2+ sympy==1.13.1+ torch==2.6.0+ typing-extensions==4.13.2
uv pip install torch --python .venv/bin/python 1.40s user 1.73s system 29% cpu 10.710 total
总共耗时10s，比传统pip下载快了一倍。
通过日志可以看到，使用pip下载是串行安装所有模块的，而使用uv进行下载使用的是多线程的并行下载，因此速度会提高不少，同时重用已下载的包减少磁盘I/O，减少CPU总工作时间。
7. 依赖冲突对比
创建一个requirements.txt，填入以下内容
langchain==0.3.23
langchain-core==0.1.0
lxml==5.2.0
传统pip安装：
pip install -r requirements.txt
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Collecting langchain==0.3.23Using cached https://pypi.tuna.tsinghua.edu.cn/packages/d4/49/6e933837da1931c9db745967282ff8bfff51bc3faec0eade846b12203b75/langchain-0.3.23-py3-none-any.whl (1.0 MB)
Collecting langchain-core==0.1.0Using cached https://pypi.tuna.tsinghua.edu.cn/packages/e9/aa/3d3e8a410d1b717e17cf162d9a1b043508a24d1c43f73749e8c854829535/langchain_core-0.1.0-py3-none-any.whl (189 kB)
Collecting lxml==5.2.0Downloading https://pypi.tuna.tsinghua.edu.cn/packages/84/1a/7442ed2964faf81746ee58358f18da42ce263999cafcd40e02d51db39755/lxml-5.2.0-cp39-cp39-macosx_10_9_universal2.whl (8.5 MB)|████████████████████████████████| 8.5 MB 3.2 MB/s
Requirement already satisfied: pydantic<3.0.0,>=2.7.4 in /Users/wuzisheng/opt/anaconda3/lib/python3.9/site-packages (from langchain==0.3.23->-r requirements.txt (line 1)) (2.10.6)
Requirement already satisfied: SQLAlchemy<3,>=1.4 in /Users/wuzisheng/opt/anaconda3/lib/python3.9/site-packages (from langchain==0.3.23->-r requirements.txt (line 1)) (1.4.32)
Collecting langchain-text-splitters<1.0.0,>=0.3.8Downloading https://pypi.tuna.tsinghua.edu.cn/packages/8b/a3/3696ff2444658053c01b6b7443e761f28bb71217d82bb89137a978c5f66f/langchain_text_splitters-0.3.8-py3-none-any.whl (32 kB)
Collecting langsmith<0.4,>=0.1.17Downloading https://pypi.tuna.tsinghua.edu.cn/packages/67/64/87a103a6a1cdca06559b09aa270e5dbfe018df4fd1b8327ce5a720441629/langsmith-0.3.32-py3-none-any.whl (358 kB)|████████████████████████████████| 358 kB 62.4 MB/s
ERROR: Cannot install -r requirements.txt (line 1) and langchain-core==0.1.0 because these package versions have conflicting dependencies.The conflict is caused by:The user requested langchain-core==0.1.0langchain 0.3.23 depends on langchain-core<1.0.0 and >=0.3.51To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflictERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/user_guide/#fixing-conflicting-dependencies
使用uv进行安装：
uv pip install -r requirements.txt --python .venv/bin/python --index-url https://pypi.tuna.tsinghua.edu.cn/simple
× No solution found when resolving dependencies:╰─▶ Because langchain==0.3.23 depends on langchain-core>=0.3.51,<1.0.0 and you require langchain==0.3.23, we can conclude that you require langchain-core>=0.3.51,<1.0.0.And because you require langchain-core==0.1.0, we can conclude that your requirements are unsatisfiable.
pip会按照文件中列出的顺序依次下载所有模块，直到触发版本冲突就报错，而且不会列出所有的冲突，修改完之后重新下载还需要重新开始，直到遇到下一个冲突，依次循环，直到手动解决所有冲突为止。
相比之下uv显得更加智能，不会先下载所有的模块，而是检查依赖是否满足，会把所有的依赖冲突都抛出来，方便一次性修改解决冲突。
总结
uv越来越频繁的出现在一些新的项目中，如最近特别多的MCP项目，基本都是用uv进行管理的。比pip更快，比conda更可靠，具备软件开发的完整功能，对于不熟悉Python项目的其他软件开发者来说也降低了学习门槛。如果是开发新的项目，不妨使用uv来进行管理吧，相信会有全新的体验。