2025-10-03
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
注意，github无法访问，用了瓦特工具箱，也很慢，最后直接访问Releases · astral-sh/uv，用迅雷下载。
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 | 显示某个命令的文档 |
首先执行以下命令初始化一个项目：
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环境版本，可以自行编辑修改。
uv中执行脚本的启动命令为：
# 与JS中`npm run dev`类似 uv run xxx
uv run 的执行逻辑为： 1. 检查当前目录中是否存在 .venv目录，若不存在则创建新环境 2. 验证环境是否包含脚本所需依赖，如果缺失依赖则自动安装 3. 在当前的虚拟环境中执行命令，不会与其他环境产生冲突
以下是uv启动命令与常规Python启动命令的对比：
| 执行命令 | 环境处理 |
|---|---|
| uv run xxx | 自动关联虚拟环境： - 优先使用当前目录下的 .venv - 若不存在会自动创建 - 无需手动激活/停用 |
| python xxx.py | 依赖当前Shell环境： - 需手动激活虚拟环境 |
用于安装包并自动更新项目配置文件（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额外增加了更新项目配置文件的功能
用于卸载包并更新项目配置
根据锁定文件精确还原依赖环境
# 同步所有依赖（包括dev） uv sync # 仅同步生产依赖 uv sync --production # 同步并清理多余包 uv sync --clean
创建/更新 uv.lock文件，用于跨平台精确版本记录
# 生成新锁定文件 uv lock # 检查更新但不写入（dry-run） uv lock --check # 强制重新解析 uv lock --update
用于可视化展示依赖关系
# 显示完整依赖树 uv tree # 仅显示指定包的依赖路径 uv tree flask # 反向追溯依赖（谁依赖了这个包） uv tree --reverse sqlalchemy # 输出为JSON格式 uv tree --format json
基本命令：
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进行安装的。
安装一个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总工作时间。
创建一个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来进行管理吧，相信会有全新的体验。