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

发布于：2025-05-31 ⋅ 阅读:(26) ⋅ 点赞:(0)

简介

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 自动关联虚拟环境：
- 优先使用当前目录下的 .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来进行管理吧，相信会有全新的体验。

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布