uv 现代化python环境管理

uv 从入门到上手

uv Learning

1. 背景

在 Python 开发中，包管理和环境隔离是每个开发者都会遇到的问题。Python 生态中的包管理工具非常多，有将 近 20 种工具，这就造成了 Python 工程化方面生态非常割裂。

了解 Python 环境管理和包管理的历史，就像在看一部“如何解决依赖地狱”的进化史。Python 社区在过去 30 年间不断在简化、规范化这些流程，但由于历史包袱，导致了现在多种工具并存的局面。

  1. 混沌时期：全局安装 (1990s - 2000s初)

在早期，Python 开发者通常直接将所有包安装在系统全局路径下。

  • EasyInstall (2004)：由 setuptools 引入，是第一个真正的 Python 包管理器。它引入了 .egg 格式，在此之前，开发者只能手动下载源码并运行 python setup.py install
  1. 隔离意识觉醒：Virtualenv 与 Pip (2008 - 2010)

为了解决全局冲突，隔离环境的概念慢慢诞生了

  • Virtualenv (2007)：由 Ian Bicking 开发，允许开发者创建隔离的 Python 环境。通过创建一个包含独立 Python 解释器和独立 site-packages 目录的目录，Virtualenv 可以让开发者在一个环境中安装和运行包，而不会影响其他环境。

  • Pip (2008)：由 Nick Coghlan 开发，是 setuptools 的替代品，提供了更简单、更强大的包管理功能。Pip 允许开发者使用 pip install 命令安装包，并使用 pip freeze 命令生成依赖列表。

  • 关键进化：2011年，Python 核心团队通过 PEP 405 将虚拟环境官方化，并在 Python 3.3 中引入了内置的 venv 模块。

  1. 多元化探索：Conda 与多版本管理 (2012 - 2016)

随着数据科学的兴起，纯 Python 的包管理已经不够用了，因为很多库（如 NumPy）依赖大量的 C/C++ 或 Fortran 编译环境。

  • Conda (2012)：Anaconda 公司推出。它不仅管理 Python 包，还管理 Python 解释器本身以及非 Python 依赖（如 OpenSSL, CUDA）。它在数据科学领域成了标准。

  • Pyenv (2011)：解决了“一台机器安装多个 Python 版本（如 3.8 和 3.10）”的问题。

  1. 现代化与规范化：依赖解析与统一工具 (2017 - 至今)

现代前端开发（如 npm/yarn）的成熟倒逼 Python 社区改进。开发者开始追求确定性安装（Lockfile）。

  • Pipenv (2017)：试图模仿 npm，将 pip 和 virtualenv 结合，引入 Pipfile.lock。虽然初期很火，但因性能和维护问题备受争议。

  • Poetry (2018)：目前的明星工具。它使用 pyproject.toml（PEP 518 规范），提供极佳的依赖解析算法，能完美解决版本冲突，是目前专业开发者的首选。

  • PPDM (2020s)：如 PDM。它利用了 PEP 582，尝试不再创建虚拟环境，而是像 Node.js 一样使用 pypackages 目录。

场景 推荐
通用 Python 开发 Poetry + pyproject.toml
科研 / 生信 / ML Conda / Mamba + pip/poetry
极致性能 / CI uv
老项目 venv + pip

在Poetry之前，环境管理和包安装都是分开的，效率很慢，冲突不断。uv刚出现的时候，问题不断争议不断，后续的更新完备才是软件生存之道

uv 是由 Astral 公司开发的一款 Rust 编写的 Python 包管理器和环境管理器，它的主要目标是提供比现有工具快 10-100 倍的性能，同时保持简单直观的用户体验。

uv 可以替代 pip、virtualenv、pip-tools 等工具，提供依赖管理、虚拟环境创建、Python 版本管理等一站式服务。

  • A single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more
  • Fast: 10-100x faster than pip, poetry, and pyenv
  • Installs and manages Python versions.
  • Includes a pip-compatible interface for a performance boost with a familiar CLI.
  • Installable without Rust or Python via curl or pip.
  • Supports macOS, Linux, and Windows.
  • uv 提供了pip兼容的接口，平滑迁移到uv

2. 安装

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

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

pip install uv

pipx install uv

安装完成之后，使用uv --version 能够查看版本信息，表示安装成功

3. 使用

3.1 管理Python版本

uv 提供了方便的 Python 版本管理功能，可以轻松地安装、切换和管理多个 Python 版本。

使用 uv python list 命令可以查看所有python 版本(包含系统中本身安装的和uv中可安装的)：

cpython-3.15.0a3-macos-x86_64-none                 <download available>
cpython-3.15.0a3+freethreaded-macos-x86_64-none    <download available>
cpython-3.14.2-macos-x86_64-none                   <download available>
cpython-3.14.2+freethreaded-macos-x86_64-none      <download available>

pypy-3.11.13-macos-x86_64-none                     <download available>
pypy-3.10.16-macos-x86_64-none                     <download available>
pypy-3.9.19-macos-x86_64-none                      <download available>
pypy-3.8.16-macos-x86_64-none                      <download available>
graalpy-3.12.0-macos-x86_64-none                   <download available>
graalpy-3.11.0-macos-x86_64-none                   <download available>
graalpy-3.10.0-macos-x86_64-none                   <download available>
graalpy-3.8.5-macos-x86_64-none                    <download available>
实现 一句话解释
CPython Python 官方参考实现，生态事实标准
PyPy 带 JIT 的 Python，实现目标是“跑得更快的 Python”
GraalPy 运行在 JVM 上的 Python，面向 Java 生态

安装特定的版本使用uv

# 安装最新的 Python 3.12
uv python install 3.12

# 安装特定版本
uv python install 3.11.6

# 安装 PyPy 版本
uv python install pypy3.10

3.2 管理虚拟环境

uv设计的理念就是基于项目的，而不是基于用户，所以uv没有列出所有虚拟环境的命令,这是与conda/poetry 不同的地方

如果依赖传统的工作方式，uv也提供了简便的命令，尤其是环境的组成

虚拟环境属于项目，不属于用户

# 创建名为 .venv 的虚拟环境（默认）
uv venv

# 激活环境（macOS/Linux）
source .venv/bin/activate

# 激活环境（Windows）
.venv\Scripts\activate

3.3 包管理

安装包,主要是替代和兼容pip:快速安装依赖

# 安装最新版本
uv pip install requests

# 安装特定版本
uv pip install requests==2.31.0

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

# add 添加删除依赖
uv add fastapi (自动创建虚拟环境并同步)
uv add --dev pytest (添加开发环境依赖)
uv remove requests

# 查看依赖树
uv tree

导出依赖

# 导出当前环境的依赖
uv pip freeze > requirements.txt

# 导出生产环境依赖（排除开发依赖）
uv pip freeze --production > requirements.txt

3.4 项目管理

初始化项目，管理依赖,基于 pyproject.toml 管理整个项目的生命周期。

切换到自己项目所在的目的，然后初始化

  1. 初始化环境
# 初始化项目
uv init
  1. 安装依赖

然后添加依赖，添加依赖之后，会自动生成.venv文件夹

# 添加依赖
uv add requests

# 更新项目依赖
uv lock --upgrade-package requests

# 删除项目依赖
uv remove requests

uv

uv

项目结构如下：

├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock
  1. 替代pipx：管理全局CLI工具

uv也可以全局安装，相当于安装在整个系统中，脱离环境也可以使用

# 全局安装 black 代码格式化工具（类似 pipx）
uv tool install black
uv tool run black ./myfile.py # 运行全局工具

# 同时提供更易用的 uvx 命令，类似 JavaScript 生态中的 npx
$ uvx pycowsay 'hello world!'

# 临时运行工具
uvx ruff check . (下载、运行并缓存，用完即走)

4. 运行脚本

Python 脚本是一个用于独立执行的 Python 文件，例如，通过 python