新一代Python管理UV完全使用指南｜附实际体验与效果对比

Python

简介

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 的执行逻辑为：

  1. 检查当前目录中是否存在 .venv目录，若不存在则创建新环境
  2. 验证环境是否包含脚本所需依赖，如果缺失依赖则自动安装
  3. 在当前的虚拟环境中执行命令，不会与其他环境产生冲突

以下是uv启动命令与常规Python启动命令的对比：

执行命令环境处理
uv run xxx自动关联虚拟环境：<br> - 优先使用当前目录下的 .venv<br> - 若不存在会自动创建<br> - 无需手动激活/停用
python xxx.py依赖当前Shell环境：<br> - 需手动激活虚拟环境

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来进行管理吧，相信会有全新的体验。

评论

暂无评论

登录

推荐阅读

网站信息

网站头像
GitHubEmailX

公告

欢迎来到我的博客！这里会分享一些技术文章和个人思考。

最新文章

归档

共76篇

查看完整归档