简介
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.git
uv 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 torch
Downloading 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.1
Downloading 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, torch
Attempting uninstall: sympy
Found existing installation: sympy 1.10.1
Uninstalling 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.23
Using 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.0
Using 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.0
Downloading 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.8
Downloading 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.17
Downloading 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.0
langchain 0.3.23 depends on langchain-core<1.0.0 and >=0.3.51
To 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 conflict
ERROR: 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来进行管理吧,相信会有全新的体验。