关于 python 的依赖管理，为什么很多人都在提倡用 uv

Posted on In , Views: Word count in article: 5.2k Reading time ≈ 5 mins.
对待一个新事物，很多人开始放弃它的同类型产品，我应该如何去探索新事物？我要不要也去试试 uv 呢？

大家都在提倡新工具、放弃旧工具时，我该如何判断？

1. 评估动机而非跟风

  • 问自己：这个工具解决了我的什么痛点？
  • 如果现有工具已经够用，新工具的边际收益是什么？

2. 渐进式探索

  • 先在个人小项目试用
  • 在非关键路径上实验
  • 观察社区成熟度和问题解决速度

3. 成本收益分析

  • 学习成本：是否容易上手？
  • 迁移成本：替换现有方案的代价？
  • 长期维护：社区是否活跃？是否有大公司支持？
  • 是否收费：公司内使用，是否会被邮件警告

4. 保持技术多样性

  • 不要把所有项目都切换到新技术
  • 维持一定的”技术组合”，降低风险
  • 新旧工具并存，根据场景选择

5. 关注信号而非噪音

  • 真实用户反馈 > 营销宣传
  • 生产环境案例 > 玩具项目
  • 长期趋势 > 短期热度

uv 为什么比较火

uv 的优势：

  • 速度极快 - 用 Rust 编写，比 pip/poetry 快 10-100 倍
  • 功能全面 - 集成了包管理、虚拟环境、Python 版本管理等
  • 兼容性好 - 可以直接替代 pip，学习成本低
  • 现代设计 - 借鉴了其他语言生态系统的优秀实践

是否需要使用 uv？这取决于使用场景：

  • 适合尝试 uv 的情况：
    • 新项目，没有历史包袱
    • 对速度有要求（大型项目、CI/CD）
    • 想简化工具链（替代 pip + venv + pyenv）
    • 个人项目，可以自由选择
  • 可以暂缓的情况：
    • 团队已有成熟的工作流（如 Poetry）
    • 项目依赖复杂，迁移成本高
    • 需要等待生态更成熟

安装 uv

Windows

方式一：默认安装，会安装到C盘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
PS D:\software> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Downloading uv 0.9.18 (x86_64-pc-windows-msvc)
Installing to C:\Users\username\.local\bin
  uv.exe
  uvx.exe
  uvw.exe
everything's installed!

To add C:\Users\username\.local\bin to your PATH, either restart your shell or run:

    set Path=C:\Users\username\.local\bin;%Path%   (cmd)
    $env:Path = "C:\Users\username\.local\bin;$env:Path"   (powershell)

# 重新打开一个窗口
PS C:\Users\username> uv --version
uv 0.9.18 (0cee76417 2025-12-16)

方式二：自定义安装位置（推荐）

step1：创建我的自定义目录：D:\software\uv

step2：在系统变量中新建变量

1
2
3
4
UV_HOME  D:\software\uv
UV_INSTALL_DIR  %UV_HOME%
UV_PYTHON_INSTALL_DIR  %UV_HOME%\python
UV_CACHE_DIR  %UV_HOME%\cache

在 Path 变量里只新建一行：%UV_HOME%

在 powershell 中输入 $env:UV_INSTALL_DIR 确定已经配置好环境变量。

执行安装命令：

1
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

step3：验证，重新打开一个窗口

1
2
3
where.exe uv
uv python dir
uv cache dir

Linux

1
2
3
4
5
6
7
8
9
10
$ curl -LsSf https://astral.sh/uv/install.sh | sh
downloading uv 0.9.18 x86_64-unknown-linux-gnu
no checksums to verify
installing to /home/test/.local/bin
  uv
  uvx
everything's installed!

$ uv --version
uv 0.9.18

创建虚拟环境

uv 可以直接替代 pip 和 virtualenv 的常用命令 Astral，先从熟悉的工作流开始：

创建虚拟环境：

1
2
3
4
5
6
# 传统方式: python -m venv .venv
uv venv  # 很快

# 激活虚拟环境（和以前一样）
source .venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows，会在执行 uv

在 windows 上执行详情，会在当前目录下生成一个 .venv 的目录

1
2
3
4
5
6
7
8
9
10
>uv venv
Using CPython 3.11.14
Creating virtual environment at: .venv
Activate with: .venv\Scripts\activate

# 或者指定目录：在当前目录生成 uvPython
>uv venv uvPython
Using CPython 3.11.14
Creating virtual environment at: uvPython
Activate with: uvPython\Scripts\activate

Windows：

1
2
D:\software>uvPython\Scripts\activate
(uvPython) D:\software>

Linux：

1
2
3
4
$ uv venv uvPython
Using CPython 3.12.9 interpreter at: miniforge3/bin/python3
Creating virtual environment at: uvPython
Activate with: source uvPython/bin/activate

安装依赖：

1
2
3
4
5
6
7
8
# 传统方式: pip install requests
uv pip install requests

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 安装开发依赖
uv pip install pytest loguru

uv 的项目管理功能

这是 uv 的核心优势，类似于 Poetry，但更快：

初始化新项目：

1
2
3
4
5
6
7
8
9
10
11
12
# 创建新项目
uv init uv_learn
cd uv_learn

# 项目结构会自动生成：
# uv_learn/
#   ├── pyproject.toml  # 项目配置
#   ├── uv.lock        # 依赖锁定文件
#   ├── main.py
#   ├── .gitignore
#   ├── .python-version
#   └── .venv

添加依赖：

1
2
3
4
5
6
7
8
# 添加生产依赖，这些依赖会安装到当前目录中的 .venv 中
uv add requests pandas

# 添加开发依赖
uv add --dev pytest black ruff

# 添加到特定依赖组
uv add --group docs sphinx

uv 的核心理念：Python 版本是项目属性，不是系统属性。

根据 uv 的项目隔离原则，uv init 创建的项目是自包含的：

  • 每个项目有独立的 .venv
  • 依赖写入 pyproject.toml 和 uv.lock
  • 与外部环境（包括 uvPython）完全隔离
1
2
3
# 如果在项目外的目录中执行 add 会提示报错
(uv-learn) D:\work>uv add xlrd
error: No `pyproject.toml` found in current directory or any parent directory

同步环境：

1
2
3
4
5
6
7
8
9
# 根据 uv.lock 安装所有依赖
uv sync

# 生产环境只安装必需依赖
uv sync --no-dev

# --dev 区别
uv add pytest           # 生产依赖（代码运行必需）
uv add --dev pytest     # 开发依赖（仅开发/测试时需要）

使用场景：

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 克隆项目后，首次设置环境
git clone project
cd project
uv sync  # 一键安装所有依赖

# 2. 切换分支后，依赖变化了
git checkout feature-branch
uv sync  # 自动调整环境

# 3. 团队成员更新了 uv.lock
git pull
uv sync  # 同步到最新依赖

运行脚本：

1
2
3
# uv 会自动确保环境同步
uv run python main.py
uv run pytest

进阶功能

Python 版本管理

1
2
3
4
5
6
7
8
9
10
11
# 安装 Python 版本
uv python install 3.12 3.13
# Windows 默认路径，例如：
# C:\Users\username\AppData\Roaming\uv\python\cpython-3.11.14-windows-x86_64-none\python.exe
# C:\Users\username\.local\bin\python3.12.exe

# 查看已安装的版本
uv python list

# 为项目指定 Python 版本
uv python pin 3.12

详情：

1
2
3
4
5
6
7
8
9
10
(uv-learn) D:\work\username\uv_learn>uv python install 3.12
Installed Python 3.12.12 in 3m 44s
 + cpython-3.12.12-windows-x86_64-none (python3.12.exe)
 
(uv-learn) D:\work\username\uv_learn>uv python list
cpython-3.12.12-windows-x86_64-none                  C:\Users\username\AppData\Roaming\uv\python\cpython-3.12.12-windows-x86_64-none\python.exe
cpython-3.12.12-windows-x86_64-none                  C:\Users\username\.local\bin\python3.12.exe
# 解释：uv 的设计行为
# AppData\Roaming\uv\python\... 真正的 CPython 安装目录（真身）
# ~\.local\bin\python3.12.exe  uv 提供的 shim / launcher（入口、转发器）

运行临时脚本

1
2
3
4
5
6
7
# 无需安装，直接运行工具
uvx ruff check .
uvx black .
uvx pytest

# 运行单文件脚本（自动管理依赖）
uv run script.py

管理开发工具

1
2
3
4
5
# 全局安装工具
uv tool install ruff black pytest

# 运行已安装的工具
ruff check .

迁移现有项目

从 pip + virtualenv 迁移：

1
2
3
4
5
6
7
8
9
10
# 1. 在项目目录中
uv init --no-readme

# 2. 导入现有依赖
uv add -r requirements.txt 
# Linux
uv add $(cat requirements.txt | grep -v '^#' | grep -v '^$')

# 3. 同步环境
uv sync

如果有的包来自于内部服务器（需要指定 url），那么在 pyproject.toml 中添加以下内容：

1
2
3
4
[[tool.uv.index]]
name = "internal-repo"
url = "http://172.xx.xxx.123:8899/simple/"
explicit = false  # 如果设为 true，则只有明确指定该源的包才会从这里下载

常用命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 环境管理
uv venv                    # 创建虚拟环境
uv python install 3.12     # 安装 Python 版本

# 项目管理
uv init                    # 初始化项目
uv add package             # 添加依赖
uv remove package          # 移除依赖
uv sync                    # 同步环境
uv lock                    # 更新锁定文件

# 运行
uv run python script.py    # 运行 Python
uv run pytest              # 运行测试
uvx tool-name              # 临时运行工具

# 兼容 pip
uv pip install package     # 安装包
uv pip list                # 列出包
uv pip freeze              # 冻结依赖

参考文档

  1. 官方文档：https://docs.astral.sh/uv/
  2. 实践指南：
  3. 快速参考：