Python 包与环境管理工具 uv

文章目录

- [一、uv 是什么](#一、uv 是什么)
- [二、三分钟装好 uv](#二、三分钟装好 uv)
- 三、先理解三个核心概念
- 四、最常用的操作与示例
- - [1. 初始化一个项目](#1. 初始化一个项目)
  - [2. 添加依赖](#2. 添加依赖)
  - [3. 运行代码（无需手动激活环境）](#3. 运行代码（无需手动激活环境）)
  - [4. 锁定与同步（可复现环境的关键）](#4. 锁定与同步（可复现环境的关键）)
  - [5. 管理 Python 版本（替代 pyenv）](#5. 管理 Python 版本（替代 pyenv）)
  - [6. 虚拟环境（兼容传统习惯）](#6. 虚拟环境（兼容传统习惯）)
  - [7. 临时运行工具（uvx，替代 pipx）](#7. 临时运行工具（uvx，替代 pipx）)
  - [8. 兼容旧工作流的 pip 接口](#8. 兼容旧工作流的 pip 接口)
  - [9. 给单文件脚本声明依赖](#9. 给单文件脚本声明依赖)
  - [10. 打包与发布](#10. 打包与发布)
- 五、一个完整小例子：数据分析项目
- 六、总结与行动建议

如果你写过几年 Python，大概都经历过这些时刻：

新开一个项目，pip install 一个稍大的包，进度条半天不动，喝完一杯咖啡还没装完；
好不容易在本地跑通的代码，发给同事却报错"ImportError"，排查半天发现是依赖版本不一致；
想试一下 Python 3.12 的新特性，却发现系统里切换版本比装包还麻烦；
虚拟环境、requirements.txt、pip、pip-tools、pyenv、poetry......工具一抓一大把，但彼此之间总差点默契。

这些痛点的根源，是 Python 的工具链长期"各自为战"。而今天要介绍的主角 uv，正是为解决这种碎片化而来。它用一种近乎"降维打击"的方式，把上述所有工具的角色收进了一个命令里。

本文面向入门读者，重点讲清三件事：uv 是什么、怎么装、日常最常用的操作怎么用，并配可直接复制运行的示例。

一、uv 是什么

uv 是由 Astral 团队（也就是写出极速 Python 代码检查工具 Ruff 的那家公司）用 Rust 编写的 Python 包与项目管理工具。它的定位非常清晰：

一个工具，替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv、twine 等一整套传统工具。

官方给出的几个关键标签：

极快：比 pip 快 10--100 倍，依赖解析与安装几乎秒级完成；
一体化：管理 Python 版本、虚拟环境、依赖、锁文件、脚本、命令行工具，甚至打包发布；
磁盘友好：全局缓存自动去重，多项目共享同一份下载；
零门槛安装：不需要预先装好 Python 或 Rust，一条命令即可装好；
全平台：macOS、Linux、Windows 均支持。

对大多数"写业务代码、做数据分析、跑自动化脚本"的场景来说，uv 几乎可以完全接管你的 Python 环境工作流。

小提示：如果你的工作涉及 CUDA、需要 C/C++ 编译的系统级库，或重度依赖 PyTorch 这类带二进制分发的深度学习框架，传统 Conda 仍有其优势。uv 与 Conda 并非互斥------普通 Python 项目用 uv，异构环境用 Conda，是很多团队的现实选择。

二、三分钟装好 uv

uv 的安装方式非常灵活，挑一种适合你的即可。

macOS / Linux（官方推荐）

bash 复制代码

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）

powershell 复制代码

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

通过已有的包管理器

bash 复制代码

pip install uv        # 已有 pip 时
pipx install uv       # 用 pipx
brew install uv       # macOS 用 Homebrew

安装完成后，验证一下：

bash 复制代码

uv --version
# 输出类似：uv 0.9.8

如果以后想升级 uv 自身，独立安装的用户直接执行：

bash 复制代码

uv self update

国内用户配置镜像源（强烈建议）

由于默认从 PyPI 官方源下载，国内网络可能偏慢。可以在项目或全局配置中使用镜像，例如清华大学源：

bash 复制代码

# 临时生效（单次命令）
UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv pip install pandas

# 写入项目配置（pyproject.toml）
# [tool.uv]
# index-url = "https://pypi.tuna.tsinghua.edu.cn/simple/"

三、先理解三个核心概念

在动手前，记住 uv 管理的三类对象，后面所有的命令都围绕它们展开：

项目（Project） ：一个带 pyproject.toml 的目录。uv 会生成 uv.lock 锁文件，确保"本机、同事、服务器"三方依赖完全一致。
脚本（Script） ：单个 .py 文件。uv 支持在文件顶部内联声明依赖，运行时自动创建隔离环境。
工具（Tool） ：由 Python 包提供的命令行程序（如 Ruff、Black）。用 uvx 可临时运行，用 uv tool install 可常驻安装。

看到这里你可能已经发现：uv 的哲学是把"环境"这件事彻底自动化，能不让你手动 activate 就不让你手动。

四、最常用的操作与示例

下面按日常使用频率，逐一演示。所有命令均可直接复制运行。

1. 初始化一个项目

bash 复制代码

uv init my_project
cd my_project

执行后会自动生成 pyproject.toml、.python-version、README.md 和源码目录。无需手动 python -m venv。

2. 添加依赖

bash 复制代码

uv add requests                 # 添加运行时依赖（最新版）
uv add "pandas>=2.0.0"          # 指定版本范围
uv add --dev pytest ruff        # 开发依赖（测试、格式化），不进生产环境
uv add "django>=4.0,<5.0"       # 精确约束
uv remove requests              # 移除依赖

每执行一次 uv add，uv 都会自动更新 pyproject.toml 并刷新 uv.lock。你几乎不需要手写 requirements 文件。

3. 运行代码（无需手动激活环境）

这是 uv 最省心的设计之一------运行命令时自动使用项目隔离环境：

bash 复制代码

uv run python main.py       # 运行脚本
uv run pytest              # 运行测试
uv run -m http.server 8000  # 以模块方式启动

第一次运行时会自动创建 .venv 并安装依赖，之后直接复用，不必再 source .venv/bin/activate。

4. 锁定与同步（可复现环境的关键）

bash 复制代码

uv lock        # 重新计算并写入 uv.lock
uv sync        # 严格按锁文件安装依赖到 .venv
uv sync --no-dev   # 只装生产依赖

团队协作时，把 pyproject.toml 和 uv.lock 一起提交到 Git。同事克隆后只需：

bash 复制代码

uv sync

即可获得与你完全相同的环境------版本、补丁号、解析结果全部一致。这对复现实验结果、部署服务尤其重要。

5. 管理 Python 版本（替代 pyenv）

uv 甚至能自己下载安装 Python，不必依赖系统已装的版本：

bash 复制代码

uv python list          # 查看已安装/可下载的版本
uv python install 3.11 3.12   # 自动下载安装多个版本
uv python pin 3.12      # 为当前项目固定版本（写入 .python-version）

固定之后，进入该目录时 uv 会自动使用 3.12，本地没有就提示你安装。跨版本测试也很方便：

bash 复制代码

uv run --python 3.10 pytest
uv run --python 3.12 pytest

6. 虚拟环境（兼容传统习惯）

如果你更习惯显式创建虚拟环境：

bash 复制代码

uv venv                  # 在当前目录创建 .venv
uv venv --python 3.11    # 指定版本
source .venv/bin/activate        # Linux/macOS 激活
.venv\Scripts\activate            # Windows 激活

7. 临时运行工具（uvx，替代 pipx）

很多小工具你只是偶尔用一次，不想污染全局环境。uvx 会在临时环境里跑完即清：

bash 复制代码

uvx ruff check .          # 临时做代码检查
uvx pycowsay "hello"      # 跑个一次性小工具

需要长期使用时，再固化安装：

bash 复制代码

uv tool install ruff     # 安装后可全局直接调用 ruff

8. 兼容旧工作流的 pip 接口

已有 requirements.txt 的老项目？uv 提供几乎一字不差的 pip 兼容命令，速度却快得多：

bash 复制代码

uv pip install -r requirements.txt   # 代替 pip install -r
uv pip compile requirements.in -o requirements.txt  # 解析并锁定
uv pip sync requirements.txt         # 严格按文件同步

这让你可以在不改造现有流程的前提下，先享受速度红利。

9. 给单文件脚本声明依赖

写个小脚本做数据抓取或一次性分析，不必建整套项目：

bash 复制代码

# example.py
import requests
print(requests.get("https://astral.sh").status_code)

bash 复制代码

uv add --script example.py requests   # 在文件顶部写入内联依赖声明
uv run example.py                     # 自动装依赖并运行

uv run 会为这个脚本单独建立隔离环境，跑完即走，绝不污染你的全局 Python。

10. 打包与发布

当项目要发布到 PyPI 时：

bash 复制代码

uv build      # 生成 dist/ 下的 sdist 与 wheel
uv publish    # 发布到索引（需提前配置凭证）

至此，连 twine 的角色也被 uv 收编了。

五、一个完整小例子：数据分析项目

把上面的命令串成一条真实工作流。假设你要做一个读取 CSV、做简单统计的小项目：

bash 复制代码

# 1. 建项目并进入
uv init sales_analysis && cd sales_analysis

# 2. 固定 Python 版本
uv python pin 3.12

# 3. 加依赖：pandas 跑分析，pytest 写测试
uv add pandas
uv add --dev pytest

# 4. 写代码（src/sales_analysis/main.py）
#    import pandas as pd
#    df = pd.read_csv("sales.csv")
#    print(df["amount"].mean())

# 5. 运行（自动建环境、装依赖）
uv run python src/sales_analysis/main.py

# 6. 锁定并同步，保证同事拿到一致环境
uv lock
uv sync

整套流程里，你一次 activate 都没敲过，版本冲突的隐患在 uv.lock 的统一约束下被提前消灭。

六、总结与行动建议

把本文浓缩成三句话：

uv 用 Rust 重写了 Python 的依赖与环境管理，速度比 pip 快一个数量级，并一个人干完了 pip、virtualenv、pyenv、poetry、pipx 的活。
核心工作流只有四步 ：uv init 建项目 → uv add 加依赖 → uv run 跑代码 → uv sync / uv lock 保证可复现。
迁移成本极低 ：老项目可用 uv pip 直接兼容，新项目从第一天就用 uv，几乎零负担。

如果你正被慢吞吞的 pip 和混乱的虚拟环境困扰，不妨就从下一个新项目开始，把第一行命令换成 uv init。几分钟之后，你大概会和我一样，再也不想回到从前。

bash 复制代码

curl -LsSf https://astral.sh/uv/install.sh | sh && uv --version