Python UV入门指南：告别缓慢，拥抱闪电般的包管理UV是Python生态系统中的新星，它以惊人的速度重新定义了包管

Python UV

什么是uv

uv是一个极快的Python包和项目管理器，用Rust编写。它旨在成为pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv等工具的一站式高性能替代品。

在这里插入图片描述

GitHub：https://github.com/astral-sh/uv

文档：https://docs.astral.sh/uv/

为什么要使用uv

⚡️ 快如闪电：它的速度比 pip 和 pip-tools 快 10-100 倍，尤其是在处理复杂的依赖关系时。
📦 一体化工具链：uv 将虚拟环境管理、包安装、依赖锁定等功能集于一身，无需在多个工具间切换。
🔄 无缝衔接：它的命令设计与 pip 非常相似，学习成本极低，可以轻松上手。
📉 智能缓存：uv 实现了全局缓存，避免了重复下载包，节省时间和磁盘空间。

安装uv

安装 uv 非常简单，官方提供了跨平台的安装脚本。

1.macOS 和 Linux

打开终端，运行以下命令：

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

2.Windows

打开 PowerShell，运行以下命令：

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

注意：可能需要关闭防护墙，否则不会安装成功，出现如下显示界面则代表安装成功

PS C:\WINDOWS\system32> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"              Downloading uv 0.7.20 (x86_64-pc-windows-msvc)                                                                          Installing to C:\Users\Administrator\.local\bin
  uv.exe
  uvx.exe
  uvw.exe
everything's installed!

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

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

使用以下命令进行更新，适用于使用独立安装程序来下载和安装uv的方式

uv self update

3.pip 果从PyPI安装，建议将uv安装到隔离环境中，例如pipx：

pipx install uv

但是，pip也可以使用：

pip install uv

更新

pip install --upgrade uv

pipx与pip的区别：

pip：主要用于安装 Python库（libraries）或模块，通常用于Python项目内部的依赖管理，或者在当前激活的虚拟环境中。

pipx：专门用于安装 Python应用程序（命令行工具），这些工具通常是想要在全局范围内使用的独立可执行程序。

验证

安装完成后，关闭并重新打开终端，然后运行以下命令来验证安装是否成功，如果能看到版本号输出，说明 uv 已经准备就绪！

uv --version

卸载

1.清理存储的数据（可选）：

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

2.删除uv和uvx二进制文件：

1.macOS和Linux

rm ~/.local/bin/uv ~/.local/bin/uvx

2.Windows

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe

镜像源

uv和pip一样，默认的下载源是官方的PyPI (Python Package Index)，其服务器地址是 https://pypi.org/simple。

uv的快主要体现在两个方面：

依赖解析: 它的解析算法和底层实现（用 Rust 编写）比 pip 快几个数量级，尤其是在依赖关系复杂时

缓存利用: 它有一个全局缓存，能非常高效地复用已下载或已构建的包

然而，下载速度本身受限于网络连接到PyPI服务器的速度。PyPI的主服务器在国外，因此，根据需要决定是否更改镜像源。

国内常用镜像源列表

选择一个你喜欢的镜像源。以下是几个常用的：

清华大学 (TUNA): https://pypi.tuna.tsinghua.edu.cn/simple

阿里云 (Aliyun): https://mirrors.aliyun.com/pypi/simple/

中国科学技术大学 (USTC): https://pypi.mirrors.ustc.edu.cn/simple/

豆瓣 (Douban): http://pypi.douban.com/simple/

华为云 (Huawei Cloud): https://repo.huaweicloud.com/repository/pypi/simple

临时使用

如果只是想临时用一下某个镜像源，可以在uv pip install命令后面加上--index-url参数。

uv pip install requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple

配置环境变量

这是uv官方推荐的方式之一，非常灵活，可以全局设置，也可以为单个项目设置。uv会读取名为UV_INDEX_URL的环境变量。

Windows: 在系统变量或用户变量中新建：

变量名：UV_DEFAULT_INDEX

变量值：镜像源地址

Linux / macOS: 编辑配置文件 ~/.bashrc，添加以下内容，保存后执行source ~/.bashrc 命令使其生效。

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

配置文件

uv 支持项目级和用户级的持久配置文件。

项目级别配置文件：

这是现代Python项目管理的最佳实践。配置写在项目根目录的pyproject.toml文件中，它只对当前项目生效。

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

用户级别配置

这是为当前用户设置的全局默认配置。一旦设置，在任何地方运行uv命令都会遵循这些规则，除非被项目级配置或命令行参数覆盖。

uv会在以下位置寻找uv.toml文件：

Windows: %APPDATA%\uv\uv.toml，通常是C:\Users\<用户名>\AppData\Roaming\uv\uv.toml

Linux: ${XDG_CONFIG_HOME}/uv/uv.toml，通常是~/.config/uv/uv.toml

编辑uv.toml文件：

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

如何使用

uv的设计哲学是成为pip的直接替代品。大多数熟悉的pip命令，只需将pip换成uv pip即可。

创建虚拟环境

告别 python -m venv .venv，使用 uv 创建虚拟环境更加简洁。

# 在当前目录下创建一个名为 .venv 的虚拟环境
uv venv

uv 默认会寻找项目中的 pyproject.toml 文件来确定使用的 Python 版本，或者可以手动指定：

# 使用 Python 3.11 创建虚拟环境
uv venv -p 3.11

激活虚拟环境

创建后，激活虚拟环境的方式和以前完全一样：

macOS / Linux:

source .venv/bin/activate

Windows (CMD):

.venv\Scripts\activate

Windows (PowerShell):

.venv\Scripts\Activate.ps1

退出虚拟环境

退出当前激活的虚拟环境，在Linux/macOS/Windons环境下执行以下命令：

deactivate

删除虚拟环境

uv venv会在当前项目目录下创建一个名为.venv目录。需要进入到包含这个虚拟环境目录的父目录，然后删除它

在Linux / macOS / Git Bash (Windows) 上执行以下命令可以直接删除虚拟环境

rm -rf .venv

安装、查看和卸载包

在激活虚拟环境后，可以像使用 pip 一样管理包。

1.安装包

# 安装单个包
uv pip install requests

# 安装多个包
uv pip install "fastapi[all]" uvicorn

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

2.列出所有已安装的包及其版本

uv pip list

3.卸载一个或多个包

uv pip uninstall requests httpx

一个完整工作流示例

从零开始创建一个项目，体验一下 uv 的完整流程。

1.创建项目并进入目录

uv init命令旨在快速创建一个新的 Python 项目工作区，并自动生成一些在现代Python项目开发中常用的标准文件和目录结构。这些文件为项目的版本控制、依赖管理、基本代码组织和文档提供了初始框架。

# 创建并初始化新项目
uv init myproject
cd myproject

# 在现有目录初始化
uv init

通过uv init命令创建项目之后，uv自动生成以下默认文件。

文件/目录	作用/解释
`.gitignore`	Git 版本控制忽略文件，指定哪些文件或目录不应被提交到 Git 仓库。
`.python-version`	指定项目所需的 Python 版本。通常与 `pyenv` 或 `asdf` 等版本管理工具配合使用。
`main.py`	标准的 Python 脚本文件，通常作为项目的入口点或包含一个简单的示例。
`pyproject.toml`	现代 Python 项目的核心配置文件，用于定义项目元数据、构建系统、依赖及各种工具配置。
`README.md`	Markdown 格式的文档文件，用于提供项目简介、安装指南、使用说明等信息。

2.创建虚拟环境

 uv venv

3.激活虚拟环境

# linux/mac
source .venv/bin/activate
 
# windows
.venv\Scripts\activate

4.依赖管理

# 安装依赖
uv sync

# 添加依赖
uv add requests
uv add "fastapi>=0.68.0"
# uv pip install "fastapi[all]"
uv add pytest --dev  # 添加开发依赖

# 删除依赖
uv remove requests

# 更新依赖
uv lock --upgrade

5.创建应用代码

创建一个 run.py 文件，内容如下：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "UV World"}

6.锁定依赖

为了保证项目在不同环境下的一致性，通常会将依赖版本锁定到一个文件中。uv 同样能胜任 pip-tools 的工作。

有2种方法：

pyproject.toml (推荐) 

requirements.in中定义顶层依赖

1.使用requirements.in

首先，创建一个 requirements.in 文件，写入顶层依赖：

fastapi[all]

然后，运行以下命令会得到一个内容详尽、版本固定的 requirements.txt 文件

 # 从 requirements.in 生成锁定的 requirements.txt
uv pip compile requirements.in -o requirements.txt

将来，新同事或在新环境部署时，只需运行以下命令即可精确复现环境：

# 使用 sync 命令可以确保环境和文件完全一致（会卸载多余的包）
uv pip sync requirements.txt

2.使用pyproject.toml 在pyproject.toml中定义依赖，例如：

[project]
name = "my-awesome-project"
version = "0.1.0"
dependencies = [
    "fastapi",
    "pydantic<3",
]
[project.optional-dependencies]
dev = [
    "pytest",
    "ruff",
]

编译生产依赖

直接编译pyproject.toml，uv会自动读取[project.dependencies]部分。

uv pip compile pyproject.toml -o requirements.txt

编译开发依赖

编译可选依赖。如果想为开发环境生成一个锁定文件，可以使用--extra标志。

uv pip compile pyproject.toml --extra dev -o dev-requirements.txt

为了确保开发依赖和生产依赖的版本兼容，通常会让开发依赖文件引用生产依赖文件：

编译时，让dev-requirements.txt引用并遵循requirements.txt中的版本约束

uv pip compile pyproject.toml --extra dev -o dev-requirements.txt -c requirements.txt

安装锁定的依赖

一旦有了requirements.txt文件，就可以使用uv pip sync来安装它。sync命令会确保虚拟环境与 requirements.txt文件完全一致，不多也不少。

# 激活虚拟环境
# Linux/Mac
source .venv/bin/activate  
# Windows:
.venv\Scripts\activate

# 使用 sync 安装锁定的依赖
uv pip sync -r requirements.txt

7.运行应用

在虚拟环境中，使用 uvicorn 运行 run.py。在访问 http://127.0.0.1:8000，就能看到应用了！

uvicorn run:app --reload

pyproject.toml

pyproject.toml 是一个由 PEP 518 引入的、使用TOML 格式的配置文件。它的目标是成为所有 Python项目配置的统一入口。

组成部分

一个典型的 pyproject.toml 文件主要由三大部分构成：

[build-system]： 构建系统的定义 (必需)
[project]： 项目的标准元数据 (推荐)
[tool]： 特定工具的配置 (可选)

[build-system]

定义构建项目所需的工具 ,告诉pip, uv等前端工具如何构建你的项目包（如 .whl 或 .tar.gz 文件）。

[build-system]
# 构建项目所需的依赖包。这里指定了hatchling，它是hatch构建系统的后端。
requires = ["hatchling"]
# 指定用于构建项目的后端。hatchling.build是hatch提供的标准构建入口。
build-backend = "hatchling.build"

requires: 一个列表，包含了构建你的包（生成一个 .whl 文件）所必需的依赖。uv 或 pip 会在一个隔离的环境中先安装这些依赖。
build-backend: 一个字符串，指向一个Python 对象（通常在一个 requires 指定的包里），这个对象知道如何执行构建操作（如打包、生成元数据等）。

[project]

定义了项目的核心元数据，用于以一种静态、声明式的方式定义项目的核心信息，遵循PEP 621 规范，这些信息会被打包工具（如pip）用来构建分发包（如 wheel 文件）

[project]
# 项目的包名，当发布到 PyPI 或通过 pip 安装时使用。
name = "my-web-app"
# 项目的当前版本号，遵循语义化版本（Semantic Versioning）规范。
version = "1.0.0"
# 项目的简短描述。
description = "基于 FastAPI 的 Web 应用"
# 项目作者信息。可以是一个列表，包含多个作者。
authors = [{name = "开发者", email = "dev@example.com"}]
# 运行该项目所需的最低 Python 版本。
requires-python = ">=3.9"
# 项目的核心依赖项。这些是应用在生产环境中运行所必需的包。
# 使用 'pip install .' 时会自动安装这些依赖。
dependencies = [
    "fastapi>=0.104.0",          # 高性能的 Web 框架
    "uvicorn[standard]>=0.24.0", # ASGI 服务器，用于运行 FastAPI 应用。
    "pydantic>=2.0.0",           # 数据验证和设置管理库，FastAPI 深度依赖它
    "sqlalchemy>=2.0.0",         # SQL 工具包和对象关系映射（ORM）库
    "alembic>=1.12.0",           # 一个基于 SQLAlchemy 的轻量级数据库迁移工具
]

dependencies: 这就是 uv 在执行 uv pip install . 或 uv pip compile pyproject.toml 时主要关注的地方。它定义了项目运行时需要哪些包。

可选的依赖组

这部分非常强大，用于定义额外的依赖信息，比如开发、测试或带特定功能的依赖。

[project.optional-dependencies]
# test组：包含运行自动化测试所需的包。
test = [
    "pytest>=7.4.0",        # 功能强大的 Python 测试框架。
    "pytest-asyncio>=0.21.0", # 用于测试 asyncio 代码的 pytest 插件。
    "httpx>=0.25.0",        # 一个现代的、支持异步的 HTTP 客户端，用于在测试中向应用发送请求。
]
# dev组：包含开发过程中使用的辅助工具，如代码格式化器、Linter 等。
dev = [
    "black>=23.0.0",  # 不妥协的代码格式化工具，保证代码风格一致。
    "ruff>=0.1.0",    # 一个极快的 Python Linter 和代码格式化工具。
    "mypy>=1.6.0",    # 静态类型检查器，用于检查代码中的类型注解。
]

使用方式：

安装核心依赖 + dev 依赖： uv pip install ".[dev]"
uv pip compile 也会识别这些组，可以为不同的环境生成不同的锁文件。

[tool]

这是 pyproject.toml实现配置统一的魔法所在。任何第三方工具都可以把自己的配置信息放在 [tool.tool_name] 这个表里。

这样，项目根目录就只需要一个 pyproject.toml，而不再需要 .pylintrc, .black.toml, .isort.cfg 等一堆文件。

# 针对uv这个工具的特定配置。
[tool.uv] 
# uv管理的开发依赖。这与[project.optional-dependencies]类似，但由uv直接管理。
# 适用于不属于项目构建包一部分的工具，如pre-commit。
dev-dependencies = [
    "pre-commit>=3.5.0", # 一个在 git commit 前自动运行代码检查（如 Linter、格式化）的框架。
]


# 用于定义在安装包时应创建的命令行脚本。这使得可以直接从命令行运行应用的特定命令。
[project.scripts]
# 创建一个名为start的可执行脚本。当在终端中运行start命令时，它实际上会执行uvicorn main:app --reload
# 这对于快速启动开发服务器非常方便。
start = "uvicorn main:app --reload"

常用命令速查表

🏡 环境管理 (替代 `venv`)

任务	命令	说明
创建虚拟环境	`uv venv`	在当前目录创建 `.venv` 虚拟环境。`uv` 会自动选择合适的 Python 版本。
指定 Python 版本	`uv venv -p 3.11`	使用指定的 Python 版本 (例如 `3.11`) 创建虚拟环境。
在指定目录创建	`uv venv ./my-env`	在 `./my-env` 目录下创建虚拟环境。
提供提示	`uv venv --prompt "my-app"`	创建带自定义提示符的虚拟环境。

📦 包管理 (替代 `pip`)

任务	命令	说明
安装包	`uv pip install <package>`	安装一个或多个包，速度极快。
从文件安装	`uv pip install -r requirements.txt`	从 `requirements.txt` 文件安装所有依赖。
从 `pyproject.toml` 安装	`uv pip install .`	安装 `pyproject.toml` 中 `[project].dependencies` 定义的依赖。
安装可选依赖	`uv pip install ".[dev,test]"`	安装 `pyproject.toml` 中的可选依赖 (`dev`, `test` 等)。
升级包	`uv pip install --upgrade <package>`	将指定的包升级到最新兼容版本。
卸载包	`uv pip uninstall <package>`	卸载一个或多个包。
列出已安装的包	`uv pip list`	以列表形式显示当前环境中所有已安装的包及其版本。
冻结依赖	`uv pip freeze`	输出当前环境中所有包及其精确版本，格式与 `pip freeze` 相同。

🔒 依赖解析与锁定 (替代 `pip-tools`)

任务	命令	说明
编译/锁定依赖	`uv pip compile <input_file> -o <output_file>`	从输入文件 (`requirements.in` 或 `pyproject.toml`) 解析并生成锁定的输出文件 (`requirements.txt`)。
从 `pyproject.toml` 编译	`uv pip compile pyproject.toml -o requirements.txt`	从 `pyproject.toml` 的主依赖生成锁文件。
编译可选依赖	`uv pip compile pyproject.toml --extra dev -o dev-requirements.txt`	编译 `pyproject.toml` 中的可选依赖。
生成哈希	`uv pip compile ... --generate-hashes`	在生成的锁文件中为每个包添加安全哈希值。
严格同步环境	`uv pip sync <requirements_file>`	严格按照锁文件同步虚拟环境，会卸载文件中未列出的多余包。

🏃 命令执行 (替代 `python -m` 和 `pipx` 部分功能)

任务	命令	说明
运行 Python 脚本	`uv run python <script.py>`	在 `uv` 管理的虚拟环境中执行 Python 脚本，无需手动激活。
运行已安装的命令	`uv run <command>`	在虚拟环境中执行任何命令，如 `uv run pytest` 或 `uv run uvicorn`。
安装全局工具	`uv tool install <tool>`	在全局隔离环境中安装命令行工具，如 `ruff`, `black`。
运行全局工具	`uv tool run <tool>`	运行一个已通过 `uv tool install` 安装的工具。
列出全局工具	`uv tool list`	查看所有已安装的全局工具。
卸载全局工具	`uv tool uninstall <tool>`	卸载一个全局工具。

⚙️ 系统与其他

任务	命令	说明
查看版本	`uv --version`	显示 `uv` 的当前版本信息。
清理缓存	`uv cache clean`	清除 `uv` 的全局包缓存，释放磁盘空间。
获取帮助	`uv --help` or `uv <subcommand> --help`	查看 `uv` 或其子命令的帮助文档。
生成 Shell 补全	`uv-completion bash` / `zsh`	生成用于 Bash 或 Zsh 的自动补全脚本。

命令说明

安装之后，可以通过uv help命令来查看帮助命令

用法: uv [OPTIONS] <COMMAND>

命令 (Commands)

命令名称 (Command)	描述 (Description)	示例 (Example)	说明 (Explanation)
`run`	在项目环境中运行命令或脚本。	`uv run pytest`	自动使用项目下的 `.venv` 虚拟环境来执行 `pytest`，无需手动激活环境。
`init`	初始化一个新项目。	`uv init my-awesome-project`	创建项目目录，并生成 `pyproject.toml` 等标准项目结构。
`add`	向项目中添加依赖项。	`uv add fastapi` `uv add pytest --dev`	自动将依赖项添加到 `pyproject.toml` 并安装，比手动修改更高效。
`remove`	从项目中删除依赖项。	`uv remove requests`	从 `pyproject.toml` 中移除依赖项，并从虚拟环境中卸载它。
`version`	读取或更新项目的版本号。	`uv version` `uv version 1.2.0`	方便地管理 `pyproject.toml` 中的版本号，支持语义化版本更新。
`sync`	根据锁文件同步项目环境。	`uv sync`	使虚拟环境与锁文件完全一致，会安装缺失的包并移除多余的包。
`lock`	根据 `pyproject.toml` 更新锁文件。	`uv lock`	解析依赖并生成精确的锁文件，是 `uv pip compile` 的高级抽象。
`export`	将项目的锁文件导出为其他格式。	`uv export -o requirements.txt`	将原生锁文件转换为通用的 `requirements.txt` 格式，以增强兼容性。
`tree`	以树状结构显示项目的依赖关系。	`uv pip tree`	`uv pip` 的子命令，非常适合用来排查依赖冲突或冗余问题。
`tool`	运行和安装全局隔离的命令行工具。	`uv tool install ruff` `uv tool run ruff .`	`uv` 的内置 `pipx` 替代品，用于安装不属于任何特定项目的全局工具。
`python`	管理 Python 版本和安装。	`uv python fetch 3.12`	(Rye-like/Future) 用于下载和管理不同的 Python 解释器版本，类似 `pyenv` 的功能。
`pip`	使用与 `pip` 兼容的接口管理包。	`uv pip install -r req.txt --upgrade`	`uv` 的核心功能，提供了与 `pip` 兼容但速度更快的接口，可无缝切换。
`venv`	创建虚拟环境。	`uv venv -p 3.11`	`uv` 自己的虚拟环境创建工具，替代 `python -m venv`，速度极快。
`build`	构建 Python 包（wheel 和 sdist）。	`uv build`	将项目打包成可分发的 `wheel` 和源码 `sdist` 文件，用于发布。
`publish`	将构建好的包发布到包索引。	`uv publish --repository pypi`	(Rye-like/Future) 替代 `twine`，用于将构建好的包上传到 PyPI 或私有仓库。
`cache`	管理 `uv` 的全局缓存。	`uv cache clean` `uv cache dir`	清理或查看 `uv` 的全局缓存位置，有助于释放磁盘空间和调试。
`self`	管理 `uv` 工具本身。	`uv self update`	用于更新 `uv` 可执行文件到最新版本，保持工具自身是最新状态。
`generate-shell-completion`	生成 shell 自动补全脚本。	`uv generate-shell-completion zsh`	为了提升命令行体验，生成用于 Shell（如 Bash, Zsh）的自动补全脚本。
`help`	显示命令的帮助文档。	`uv --help` `uv pip --help`	获取任何 `uv` 命令或子命令的详细用法和可用选项。

缓存选项 (Cache Options)

选项名称	描述	环境变量
`-n`, `--no-cache`	避免读写缓存，而是使用一个临时目录进行操作（操作期间有效）	`UV_NO_CACHE`
`--cache-dir <CACHE_DIR>`	缓存目录的路径	`UV_CACHE_DIR`

Python 选项 (Python Options)

选项名称	描述	环境变量
`--managed-python`	要求使用 uv 管理的 Python 版本	`UV_MANAGED_PYTHON`
`--no-managed-python`	禁用使用 uv 管理的 Python 版本	`UV_NO_MANAGED_PYTHON`
`--no-python-downloads`	禁用 Python 的自动下载	`UV_PYTHON_DOWNLOADS=never`

全局选项 (Global Options)

选项名称	描述	环境变量
`-q`, `--quiet...`	使用安静输出
`-v`, `--verbose...`	使用详细输出
`--color <COLOR_CHOICE>`	控制输出中颜色的使用 `[auto, always, never]`
`--native-tls`	是否从平台的原生证书存储区加载 TLS 证书	`UV_NATIVE_TLS`
`--offline`	禁用网络访问	`UV_OFFLINE`
`--allow-insecure-host <HOST>`	允许与主机进行不安全连接	`UV_INSECURE_HOST`
`--no-progress`	隐藏所有进度输出	`UV_NO_PROGRESS`
`--directory <DIRECTORY>`	在运行命令前切换到给定目录
`--project <PROJECT>`	在给定项目目录内运行命令	`UV_PROJECT`
`--config-file <FILE>`	用于配置的 `uv.toml` 文件的路径	`UV_CONFIG_FILE`
`--no-config`	避免发现配置文件 (`pyproject.toml`, `uv.toml`)	`UV_NO_CONFIG`
`-h`, `--help`	显示此命令的简洁帮助
`-V`, `--version`	显示 uv 版本

Python UV入门指南：告别缓慢，拥抱闪电般的包管理