第1章：uv 简介

1.1 什么是uv

uv是由Astral团队开发的高性能Python包管理器和虚拟环境管理器，使用Rust语言实现，旨在替代传统的pip、pipenv、poetry、virtualenv等工具。uv的核心定位是为Python开发者提供一个快速、可靠、功能全面的依赖管理解决方案。

uv的设计理念是"一次编写，到处运行"，通过严格遵循PEP标准，确保与现有Python生态系统的完全兼容性，同时提供远超传统工具的性能表现。

1.2 主要特性

极致性能：采用Rust语言编写，依赖解析和包安装速度比传统工具快10-100倍，特别是在大型项目中优势更为明显

功能集成：内置虚拟环境管理、依赖解析、包安装、版本锁定、脚本运行、包构建发布等全流程支持，无需额外安装其他工具
兼容性：完全兼容PEP 508（依赖规范）、PEP 517/518（构建系统）、PEP 621（项目元数据）等标准，支持pyproject.toml、requirements.txt、setup.py等多种配置格式
跨平台：原生支持Windows、macOS、Linux三大操作系统，提供一致的使用体验
智能缓存：全局缓存下载的包和构建结果，避免重复下载和编译
安全可靠：内置依赖漏洞扫描、哈希校验、签名验证等安全功能，保障依赖供应链安全

1.3 与传统工具对比

1.3.1 vs pip + virtualenv 组合

优势：uv将虚拟环境管理和包管理集成在单个工具中，无需在多个工具间切换；依赖解析速度快，避免了pip常见的解析超时和版本冲突问题；内置锁文件机制，无需手动管理requirements.txt
兼容性：完全支持pip的所有命令行参数和requirements.txt格式，可以无缝替换pip

1.3.2 vs Poetry

优势：性能提升显著，特别是大型项目的依赖解析速度是Poetry的10-50倍；命令设计更简洁直观，学习成本更低；更严格的PEP标准兼容性，减少了自定义行为带来的兼容性问题
兼容性：支持直接导入Poetry的pyproject.toml配置和poetry.lock文件，迁移成本低

1.3.3 vs Pipenv

优势：性能优势巨大，解决了Pipenv长期存在的解析速度慢和稳定性问题；功能更全面，包含了Python版本管理、工作空间等高级功能；维护活跃，更新迭代速度快
兼容性：支持导入Pipfile和Pipfile.lock，平滑迁移

1.3.4 vs Conda

优势：更轻量级，启动速度快；专注于Python生态，与PyPI兼容性更好；磁盘占用更小，缓存机制更高效
适用场景：uv更适合纯Python项目，Conda更适合数据科学场景中需要管理非Python依赖（如C/C++库）的情况

1.4 适用场景

个人开发环境管理：快速创建和管理多个项目的虚拟环境，避免依赖冲突
项目依赖管理：精确管理项目依赖版本，确保开发、测试、生产环境的一致性
CI/CD流水线：极快的依赖安装速度可以显著缩短构建时间，提高CI/CD效率
多项目并行开发：工作空间功能支持在单个仓库中管理多个相关项目，共享依赖
团队协作环境一致性：通过uv.lock文件确保团队所有成员使用完全相同的依赖版本
开源库开发：内置的构建和发布功能，简化Python库的开发和发布流程

第2章：安装指南

2.1 系统要求

支持的操作系统：

Windows 10 及以上版本

macOS 10.15 (Catalina) 及以上版本
Linux（支持glibc 2.17+和musl libc的主流发行版）
Python版本要求：Python 3.7 及以上版本（uv本身不依赖Python安装，但管理的项目需要Python环境）
硬件要求：最低1GB内存，推荐2GB以上内存（大型项目依赖解析需要更多内存）

2.2 安装方法

2.2.1 官方脚本安装（推荐）

官方提供的安装脚本会自动检测系统环境，下载对应的预编译二进制文件并配置环境变量。

Linux/macOS 安装命令：

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

Windows PowerShell 安装命令：

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

Windows CMD 安装命令：

curl -LsSf https://astral.sh/uv/install.ps1 -o install.ps1 && powershell -ExecutionPolicy ByPass -File install.ps1 && del install.ps1

2.2.2 包管理器安装

使用pip安装

如果系统中已经有Python环境，可以直接使用pip安装uv：

pip install uv

注意：使用pip安装的uv不会包含自更新功能，升级时需要重新使用pip命令。

使用Homebrew安装（macOS）

brew install uv

使用Scoop安装（Windows）

scoop install uv

使用Chocolatey安装（Windows）

choco install uv

使用apt安装（Debian/Ubuntu）

curl -fsSL https://packages.astral.sh/linux/astral.asc | sudo gpg --dearmor -o /usr/share/keyrings/astral-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/astral-archive-keyring.gpg] https://packages.astral.sh/linux/debian/ stable main" | sudo tee /etc/apt/sources.list.d/astral.list
sudo apt update && sudo apt install uv

使用yum/dnf安装（RHEL/CentOS/Fedora）

For RHEL/CentOS

sudo dnf config-manager --add-repo https://packages.astral.sh/linux/rhel/astral.repo
sudo dnf install uv

For Fedora

sudo dnf config-manager --add-repo https://packages.astral.sh/linux/fedora/astral.repo
sudo dnf install uv

2.2.3 预编译二进制下载

如果无法使用上述安装方法，可以手动下载预编译二进制文件：

访问官方发布页面：https://github.com/astral-sh/uv/releases
下载对应操作系统和架构的最新版本压缩包
解压后将uv可执行文件放到系统PATH包含的目录中（如/usr/local/bin或%USERPROFILE%\AppData\Local\Programs\uv\bin）
手动将uv的安装目录添加到系统环境变量PATH中

2.3 安装验证

安装完成后，打开新的终端窗口，执行以下命令验证安装是否成功：

uv --version

如果安装成功，会输出类似如下的版本信息：

uv 0.4.0 (a1b2c3d 2024-01-15)

进行基础功能测试：

uv --help

该命令会显示uv的帮助信息，列出所有可用命令。

2.4 版本升级

升级到最新正式版

如果是通过官方脚本安装的uv，可以使用自更新功能：

uv self update

升级到预发布版

如果想体验最新功能，可以升级到预发布版本：

uv self update --prerelease

指定版本升级

可以升级到指定的版本：

uv self update --version 0.4.0

注意：如果是通过包管理器（如pip、brew、scoop等）安装的uv，需要使用对应包管理器的升级命令。

2.5 卸载方法

官方卸载脚本

Linux/macOS 卸载命令：

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

Windows PowerShell 卸载命令：

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

手动卸载步骤

删除uv可执行文件：

Linux/macOS：rm ~/.cargo/bin/uv 或 rm /usr/local/bin/uv

Windows：删除 %USERPROFILE%.cargo\bin\uv.exe或安装时指定的目录

删除uv的配置和缓存目录：

Linux/macOS：rm -rf ~/.cache/uv ~/.config/uv

Windows：rmdir /s /q %LOCALAPPDATA%\uv\cache %APPDATA%\uv

从系统环境变量PATH中移除uv的安装目录

第3章：快速上手

3.1 基本概念

3.1.1 虚拟环境

虚拟环境是Python项目的隔离运行环境，每个项目可以拥有独立的依赖包版本，不会与其他项目或系统Python环境冲突。uv会自动管理虚拟环境的创建、激活和销毁。

3.1.2 依赖锁文件（uv.lock）

uv.lock是uv生成的依赖锁定文件，记录了所有依赖包的精确版本、下载地址和哈希校验值。确保在任何环境下安装的依赖版本完全一致，避免了"在我机器上能运行"的问题。

3.1.3 pyproject.toml 配置文件

pyproject.toml是PEP 621定义的Python项目标准配置文件，用于存储项目元数据、依赖声明、构建配置等信息。uv使用pyproject.toml作为默认的配置文件格式。

3.1.4 开发依赖 vs 生产依赖

生产依赖：项目运行时必须的依赖包，如web框架、数据库驱动等
开发依赖：仅在开发过程中需要的依赖包，如测试框架、代码检查工具、文档生成工具等

3.2 第一个uv项目

3.2.1 项目初始化

步骤1：新建项目目录

mkdir my-uv-project
cd my-uv-project

步骤2：初始化项目

uv init

执行该命令后，uv会自动完成以下操作：

创建虚拟环境（默认在项目目录下的.venv文件夹）
生成pyproject.toml配置文件
生成README.md项目说明文件
生成.gitignore文件（如果不存在）
创建项目主模块目录

自动生成的文件结构说明：

my-uv-project/

├── .venv/ # 虚拟环境目录

├── pyproject.toml # 项目配置文件

├── uv.lock # 依赖锁文件

├── README.md # 项目说明文档

├── .gitignore # Git忽略文件

└── my_uv_project/ # 项目主模块目录

└── __init__.py # 模块初始化文件

pyproject.toml初始内容示例：

[project]

name = "my-uv-project"
version = "0.1.0"
description = ""
authors = [

{ name = "Your Name", email = "your.email@example.com" },

]

requires-python = ">=3.11"

dependencies = []

[tool.uv]

dev-dependencies = []

3.2.2 安装第一个包

安装生产依赖：

uv add requests

执行该命令后，uv会：

解析requests的最新版本及其依赖
安装requests到虚拟环境
更新pyproject.toml中的dependencies列表
更新uv.lock文件，记录所有依赖的精确版本

观察文件变化：

pyproject.toml中会添加：dependencies = ["requests>=2.31.0"]
uv.lock文件会记录requests及其所有依赖的精确版本、哈希值等信息

安装开发依赖：

uv add --dev pytest

pytest会被添加到dev-dependencies列表中，不会在生产环境中安装。

3.2.3 运行项目代码

创建测试脚本：

在项目根目录创建 test_requests.py文件：

import requests

def main():
response = requests.get("https://api.github.com")
print(f"GitHub API Status: {response.status_code}")
print(f"Rate Limit: {response.headers['X-RateLimit-Limit']}")

if __name__ == "__main__":

main()

使用uv运行脚本：

uv run test_requests.py

uv会自动激活当前项目的虚拟环境并运行脚本，无需手动激活环境。

激活虚拟环境的两种方式：

手动激活（长期使用）：
Linux/macOS：source .venv/bin/activate
Windows PowerShell：.venv\Scripts\Activate.ps1
Windows CMD：.venv\Scripts\activate.bat

激活后，终端提示符会显示虚拟环境名称，此时执行的所有Python命令都会使用虚拟环境中的版本。

临时激活（单次命令）：
使用 uv run 前缀，如：

uv run python --version
uv run pip list

这种方式不需要手动激活和退出环境，适合执行单个命令。

退出虚拟环境：

如果手动激活了虚拟环境，执行以下命令退出：

deactivate

3.3 现有项目迁移

3.3.1 从requirements.txt迁移

如果项目使用requirements.txt管理依赖，可以直接导入：

uv pip install -r requirements.txt

或者初始化项目时自动导入：

uv init --from-requirements requirements.txt

3.3.2 从Poetry/Pipenv项目迁移

uv会自动识别Poetry的pyproject.toml和poetry.lock文件，以及Pipenv的Pipfile和Pipfile.lock文件。只需要在项目根目录执行：

uv sync

uv会自动导入现有配置并创建对应的虚拟环境和uv.lock文件。

3.3.3 现有虚拟环境导入

如果已经有现成的虚拟环境，可以指定uv使用该环境：

uv venv --python /path/to/existing/venv/bin/python

或者设置环境变量：

export VIRTUAL_ENV=/path/to/existing/venv

3.4 常用命令速览

环境相关命令

uv venv                    # 在当前目录创建 .venv
uv venv .venv-py312 -p 3.12  # 用指定 Python 创建虚拟环境
uv python list            # 列出可用/已安装的 Python 版本
uv python install 3.12    # 安装指定 Python 版本
uv python pin 3.12        # 为项目固定 Python 版本

依赖相关命令

uv add <package>                 # 添加依赖
uv add --dev <package>           # 添加开发依赖
uv remove <package>              # 删除依赖
uv lock                          # 生成或更新 uv.lock
uv lock --upgrade                # 升级全部可升级依赖并更新锁文件
uv lock --upgrade-package ruff   # 升级指定依赖
uv sync                          # 按锁文件同步环境
uv export -o requirements.txt    # 导出 requirements.txt
uv tree                          # 显示依赖树
uv pip list                      # 查看当前环境已安装包

运行相关命令

uv run <script>                  # 运行脚本
uv run python -m pytest          # 在项目环境中运行命令
uv tool run ruff check .         # 临时运行工具包命令
uv build                         # 构建源码包和 wheel

说明：不少旧教程中会出现 uv update、uv list、uv outdated、uv venv show 等写法。当前版本的 uv 更常通过 uv lock、uv sync、uv tree、uv pip list、uv python 等命令完成相同工作。

第4章：虚拟环境管理

4.1 虚拟环境基础

4.1.1 虚拟环境的作用和优势

虚拟环境的核心价值是隔离。每个项目拥有独立的解释器与依赖集合，可以避免：

不同项目之间的版本冲突
系统 Python 被污染
团队成员环境不一致

uv 对虚拟环境的处理理念很直接：

项目默认使用项目根目录下的 .venv
大多数情况下不需要手动激活环境
执行 uv run ...、uv add ...、uv sync 时，uv 会自动发现并使用项目环境

4.1.2 uv 的虚拟环境存储位置

默认位置：项目目录下的 .venv
可通过 uv venv 创建到其他位置
在项目根目录运行时，可以通过环境变量 UV_PROJECT_ENVIRONMENT 修改默认环境目录名

4.1.3 虚拟环境的识别规则

根据当前 uv 的帮助信息，uv 会优先按如下顺序发现 Python 环境：

当前已激活的虚拟环境
当前目录及父目录中的 .venv
系统 Python 或 uv 管理的 Python

这意味着在常规项目内，执行 uv run python 往往就会自动落到项目自己的 .venv。

4.2 创建虚拟环境

4.2.1 项目内虚拟环境

默认创建方式：

uv venv

该命令会在当前目录创建 .venv。

指定 Python 版本创建：

uv venv -p 3.12
uv venv -p cpython@3.12

如果本机没有对应版本，uv 可以根据配置自动下载。

创建到自定义位置：

uv venv .venv-py312
uv venv .cache/dev-env -p 3.12

带种子包创建：

uv venv --seed

这会把 pip、setuptools、wheel 等种子包放入环境，便于与传统工作流兼容。

4.2.2 全局或命名虚拟环境

当前版本 uv 的 venv 子命令是“创建一个虚拟环境到指定路径”，并不是维护一套独立的“命名环境注册表”。因此：

可以创建任意路径的环境，例如 uv venv D:\envs\myenv
但没有单独的 uv venv list 或 uv venv remove 子命令去集中管理所有环境

示例：

uv venv D:\envs\quant-dev -p 3.12

如果你希望长期维护多个命名环境，通常做法是：

自己约定一个目录，例如 D:\envs\
每个环境一个子目录
用 uv run --project <项目目录> 或激活脚本切换使用

4.3 虚拟环境操作

4.3.1 激活虚拟环境

Linux/macOS：

source .venv/bin/activate

Windows PowerShell：

.venv\Scripts\Activate.ps1

Windows CMD：

.venv\Scripts\activate.bat

4.3.2 临时激活

uv 更推荐的方式通常不是手动激活，而是直接运行：

uv run python --version
uv run pytest
uv run quant --help

这类命令会自动使用项目环境，更适合脚本化、CI 和团队协作。

4.3.3 查看虚拟环境信息

当前版本没有单独的 uv venv show。常用替代方式包括：

uv run python --version
uv run python -c "import sys; print(sys.executable)"

在 Windows 下也可以：

uv run python -c "import sys, site; print(sys.prefix); print(site.getsitepackages())"

4.3.4 退出虚拟环境

若使用了手动激活，可执行：

deactivate

4.4 虚拟环境管理

4.4.1 列出环境

当前版本 uv 没有集中列出所有虚拟环境的命令。可采用以下做法：

统一约定环境目录并自行查看
使用 uv python list 查看可用解释器
用项目根目录的 .venv 作为标准约定，减少“列出环境”的需求

4.4.2 删除虚拟环境

当前版本 uv 没有 uv venv remove，删除方式就是直接删除环境目录。

Windows PowerShell 示例：

Remove-Item -Recurse -Force .venv

Linux/macOS 示例：

rm -rf .venv

4.4.3 重建环境

最常见的“修复环境”动作是删除并重建：

uv venv --clear
uv sync

或者：

rm -rf .venv
uv sync

其中 uv sync 会在需要时自动创建项目环境。

4.5 高级配置

4.5.1 配置默认虚拟环境位置

可以通过以下方式间接控制环境位置：

在项目根目录使用标准 .venv
通过 UV_PROJECT_ENVIRONMENT 变更默认环境目录名
通过 uv venv 显式创建到特定路径

4.5.2 Python 版本管理

uv 内置了 Python 版本管理能力：

uv python list
uv python install 3.12
uv python pin 3.12
uv python find 3.12

相比依赖 pyenv、asdf 或手工安装，这种方式更统一，也更适合和项目约束联动。

4.5.3 Shell 集成

uv 自身不强依赖“自动激活 shell”工作流；在团队协作里更建议：

命令前统一加 uv run
将启动命令写进 README、任务脚本或 CI
降低对交互式 shell 状态的依赖

第5章：依赖包管理

5.1 依赖管理基础

5.1.1 依赖类型

生产依赖：放在 project.dependencies，运行时必须存在
开发依赖：通常通过 uv add --dev 加入开发组，仅开发阶段需要
可选依赖：可按 extra 组织，按需安装
依赖组：可通过 --group 管理测试、文档、lint 等分组

5.1.2 版本约束语法

常见写法包括：

精确版本：package==1.0.0
最低版本：package>=1.0.0
范围版本：package>=1.0.0,<2.0.0
同主版本：通过 uv add --bounds major package
同次版本：通过 uv add --bounds minor package
精确锁定：通过 uv add --bounds exact package

此外还支持：

Git 依赖
本地路径依赖
可编辑依赖
直接 URL 依赖

5.2 添加依赖

5.2.1 添加生产依赖

uv add requests
uv add pandas numpy

5.2.2 添加开发依赖

uv add --dev pytest
uv add --dev ruff mypy

5.2.3 添加到指定依赖组

uv add --group docs mkdocs
uv add --group lint ruff

5.2.4 指定版本或版本策略

uv add "fastapi>=0.116,<1.0"
uv add --bounds exact ruff
uv add --bounds major httpx

5.2.5 安装预发布版本

对预发布版，通常直接写入版本约束即可，例如：

uv add "package>=2.0.0rc1"

5.2.6 从 Git、本地路径安装

uv add git+https://github.com/encode/httpx
uv add .\libs\my_package
uv add --editable .

说明：

当前版本 uv 常会把 Git、本地路径等来源信息写入 [tool.uv.sources]
如果使用 uv add --raw，则会尽量按你输入的原始 requirement 直接写入依赖声明

5.3 依赖查询

5.3.1 查看已安装依赖

uv pip list
uv pip freeze

5.3.2 查看单个包详情

uv pip show pandas

5.3.3 查看依赖树

uv tree

5.3.4 查询说明

当前版本 uv 没有独立的 uv list、uv show、uv outdated 顶层命令。常见替代关系如下：

uv list -> uv pip list
uv show -> uv pip show
uv outdated -> 更常见做法是 uv lock --upgrade-package 试升级，或重新解析后观察 lockfile 变化

5.4 更新依赖

5.4.1 更新所有依赖

uv lock --upgrade
uv sync

第一步更新锁文件，第二步把环境同步到新锁文件版本。

5.4.2 更新指定包

uv lock --upgrade-package pandas
uv sync

5.4.3 仅更新锁文件

uv lock
uv lock --upgrade

5.4.4 校验锁文件是否最新

uv lock --check

这在 CI 中非常有用，可以防止 pyproject.toml 与 uv.lock 不一致。

5.5 删除依赖

5.5.1 删除依赖包

uv remove requests

5.5.2 删除开发依赖

uv remove --group dev pytest

删除完成后，建议执行一次：

uv sync

5.6 依赖同步

5.6.1 根据锁文件同步环境

uv sync

默认会做“精确同步”，把环境调整到与锁文件一致。

5.6.2 仅同步生产依赖

uv sync --no-dev

5.6.3 仅同步某些依赖组

uv sync --group docs
uv sync --only-group dev

5.6.4 不移除额外包

uv sync --inexact

5.7 依赖导出

5.7.1 导出为 requirements.txt

uv export -o requirements.txt

5.7.2 导出为 pylock.toml

uv export --format pylock.toml -o pylock.toml

5.7.3 排除开发依赖或本地包

uv export --no-dev -o requirements.txt
uv export --no-emit-local -o requirements-third-party.txt

5.7.4 不输出哈希

uv export --no-hashes -o requirements.txt

第6章：项目配置

6.1 pyproject.toml 配置详解

6.1.1 [project] 区段

该区段是标准 PEP 621 项目元数据区，常见字段包括：

name
version
description
readme
requires-python
dependencies
optional-dependencies
scripts

结合本仓库当前配置，可以看到如下典型结构：

[project]

name = "quant-local"
version = "0.1.0"

requires-python = ">=3.13"

[project.scripts]

quant = "quant_local.cli:app"

6.1.2 [tool.uv] 区段

该区段用于 uv 相关扩展配置，常见用途包括：

开发依赖组
默认依赖组行为
解析冲突声明
其他 uv 特定项目设置

本仓库目前使用了：

[tool.uv]

dev-dependencies = [

"pytest>=8.0.0",

"pytest-cov>=4.0.0",

]

6.1.3 [tool.uv.sources] 区段

当你添加 Git、本地路径、直接 URL 等来源依赖时，uv 常会在这里记录来源信息。

这有两个好处：

让 project.dependencies 保持更干净
把来源与版本控制信息单独管理

如果你希望“按输入原样写入依赖”，可以考虑 uv add --raw。

6.2 索引源配置

6.2.1 国内镜像配置

本仓库已经使用了清华镜像：

[[tool.uv.index]]

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

这种配置适合国内网络环境，能够显著减少下载失败和解析等待。

6.2.2 多源优先级

当前 uv 支持多索引，并通过 index-strategy 决定解析策略。默认倾向于“先命中第一个有该包的索引”，这样能降低依赖混淆风险。

6.2.3 私有源认证

对于私有源，通常可通过以下方式配合：

环境变量
凭证管理器
keyring 子进程支持

如果涉及公司内部源，优先使用受控凭证方式，不要把令牌直接写进仓库。

6.3 环境变量配置

常见环境变量示例：

UV_PROJECT_ENVIRONMENT：修改项目环境目录名
UV_PYTHON：指定 Python 解释器请求
UV_CACHE_DIR：指定缓存目录
UV_DEFAULT_INDEX：设置默认索引
UV_INDEX：附加索引
UV_LOCKED：要求锁文件保持不变
UV_FROZEN：只按现有锁文件执行

使用建议：

项目通用配置尽量放进 pyproject.toml
机器相关配置优先放环境变量
CI 里显式设置 UV_LOCKED=1 或 UV_FROZEN=1，便于保证结果稳定

6.4 全局配置

当前版本 uv 主要通过以下位置读取配置：

项目内 pyproject.toml
独立的 uv.toml
环境变量

需要注意：当前版本并没有单独的 uv config 顶层子命令，因此很多旧文章里提到的 uv config ... 并不适用于现在的命令集。

第7章：高级功能

7.1 工作空间（Workspace）管理

uv 支持 workspace 概念，但当前版本不是通过 uv workspace 单独管理，而是通过项目结构和命令参数协同完成。

在 workspace 场景里，常见相关参数包括：

--package ：操作指定成员包
--all-packages：作用到所有成员包
--workspace：在某些命令中把本地路径加入 workspace 成员

适合场景：

Monorepo
多个内部 Python 包共存
核心库与应用共仓开发

7.2 脚本运行

7.2.1 基础运行

uv run python script.py
uv run pytest
uv run quant sync-data

7.2.2 运行带内联依赖的脚本

当前 uv 支持 PEP 723 脚本元数据。对于单文件脚本，依赖可以写在脚本里，由 uv run script.py 临时创建环境并运行。

这种方式适合：

一次性脚本
数据处理小工具
教学示例

7.2.3 工具命令运行

uv tool run ruff check .
uv tool run mypy quant_local

如果你希望长期安装某个工具，也可以使用：

uv tool install ruff
uv tool list
uv tool upgrade ruff

7.3 包发布

7.3.1 构建包

uv build

通常会产出：

sdist
wheel

7.3.2 发布到索引

uv publish

如果发布到私有源，需要提前准备认证信息。

7.4 Python 版本管理

这是 uv 相比传统 pip + venv 工作流非常实用的地方。

常用命令：

uv python list
uv python install 3.12
uv python find 3.12
uv python pin 3.12
uv python uninstall 3.12

适合场景：

本机尚未安装对应 Python
多项目需要不同 Python 版本
CI 或新机器初始化环境

7.5 缓存管理

uv 的速度优势很大一部分来自缓存机制。

常用命令：

uv cache dir
uv cache clean
uv cache prune

建议：

日常不要频繁清空缓存
CI 可以结合缓存目录做持久化
只有在缓存损坏或磁盘空间紧张时再清理

7.6 安全与可重复性

当前版本 uv 顶层命令中没有独立的 uv audit。但在安全实践上，仍建议关注：

使用锁文件固定版本
使用可信索引源
使用默认安全的多源解析策略
在 CI 中执行 uv lock --check
对第三方依赖另行接入安全扫描工具

如果团队有供应链安全要求，可以把依赖审计交给专门工具，而 uv 负责版本锁定和安装一致性。

第8章：工作流最佳实践

8.1 个人开发工作流

推荐流程：

uv init 初始化项目
uv python pin 3.12 固定 Python 版本
uv add / uv add --dev 添加依赖
uv run ... 执行脚本、测试和工具
uv lock --check 检查锁文件一致性

个人开发建议：

保持 .venv 作为项目默认环境目录
尽量不要混用系统 pip install
使用 uv run 代替“先激活再运行”

8.2 团队协作工作流

8.2.1 项目配置标准化

统一使用 pyproject.toml
提交 uv.lock
统一 Python 版本要求
将常用命令写入 README 或任务脚本

8.2.2 CI/CD 集成建议

在 CI 中常见做法：

uv sync --frozen --no-dev
uv run pytest

或在校验阶段：

uv lock --check
uv sync --frozen

8.3 不同场景最佳实践

8.3.1 数据科学项目

固定 Python 与关键数值库版本

使用镜像源减少大包下载失败

在 CI 或共享机器上利用缓存

8.3.2 Web 开发项目

这一部分结合 uvicorn 官方文档说明 uv 与 Web 服务启动的配合方式。

如果项目使用 ASGI 服务，推荐：

uv add "uvicorn[standard]"
uv run uvicorn main:app --reload

说明：

uvicorn[standard] 通常会带上 watchfiles、websockets、httptools 等开发期常用增强依赖
uv run uvicorn ... 不依赖你是否已手动激活 .venv
--reload 适合本地开发

生产场景常见做法：

uv add uvicorn
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

结合 uvicorn 官方文档，还需要注意：

--reload 与 --workers 互斥，不能一起用
如果使用应用工厂，可执行 uv run uvicorn --factory main:create_app
如果要在代码中启动，可以用 uvicorn.run("main:app", ...)

8.3.3 命令行工具开发

如果你的项目像本仓库一样已经有 [project.scripts]：

[project.scripts]

quant = "quant_local.cli:app"

那么开发阶段很适合：

uv run quant --help

8.3.4 库开发项目

使用 uv build 验证打包输出

把测试、lint、docs 放入不同依赖组

在发布前确保锁文件与元数据同步

8.4 性能优化技巧

使用本地镜像或公司代理源

利用 uv 的缓存，不要频繁清空

在 Docker / CI 中先安装第三方依赖，再安装本地项目

使用 uv sync --frozen 减少不必要解析

8.5 常见陷阱与规避

不要把系统 pip 和项目 uv 工作流混在一起

不要随手删除 uv.lock 后忘记重新提交

不要在生产环境使用 --reload

对多源解析，优先使用默认安全策略，避免依赖混淆

第9章：常见问题（FAQ）

9.1 安装问题

安装失败常见原因

网络访问 PyPI 慢或超时

公司代理或证书链问题

Python 版本不满足项目约束

解决建议

配置国内镜像源

必要时启用系统证书存储或公司代理证书

先执行 uv python list / uv python install 准备解释器

9.2 虚拟环境问题

虚拟环境无法激活

先确认环境是否存在：

uv run python --version

如果能运行，通常说明环境本身没有问题，只是 shell 激活脚本没有生效。

Python 版本不匹配

检查：

uv run python --version
uv python find 3.12

9.3 依赖安装问题

依赖解析失败

常见原因：

版本约束彼此冲突
某些包在当前 Python 版本无可用 wheel
源中没有对应版本

排查建议：

缩小版本约束范围
切换 Python 版本再试
使用 uv tree 观察依赖关系

二进制包安装问题

Windows 上部分科学计算包对 Python 版本和架构更敏感，优先选择官方支持好的 Python 版本组合。

9.4 性能问题

依赖解析慢怎么办

配置镜像源
复用缓存
减少不必要的源切换

安装速度慢怎么办

检查是否每次都在清缓存
在 CI 中缓存 uv 缓存目录
优先使用 wheel 丰富的版本组合

9.5 兼容性问题

与其他工具共存

可以共存，但建议一个项目只选择一套主工作流：

要么用 uv
要么继续用 Poetry / Pipenv

混用最容易导致锁文件、环境和依赖声明不一致。

旧项目迁移时最常见的问题

requirements.txt 能装，但缺少项目元数据
原来依赖是手工 pip 安装，没有完整声明
Python 版本约束没有写进项目配置

9.6 其他常见问题

uv.lock 要不要提交到 Git

通常要提交。这样团队成员、CI 与生产环境可以保持一致依赖解析结果。

如何回滚依赖版本

回退 pyproject.toml
回退 uv.lock
再执行 uv sync --frozen

如何清理未使用依赖

从 pyproject.toml 移除对应依赖
执行 uv remove
再执行 uv sync

私有源配置问题

优先把凭据放在环境变量或凭证管理器里，不要提交到仓库。

附录A：命令参考大全

A.1 核心命令

uv init：初始化项目
uv add：添加依赖
uv remove：删除依赖
uv lock：生成或更新锁文件
uv sync：同步项目环境
uv run：在项目环境中运行命令或脚本

A.2 管理命令

uv self update：升级 uv 自身
uv python：管理 Python 版本
uv cache：管理缓存
uv tool：管理全局/临时工具

A.3 信息查询命令

uv tree：查看依赖树
uv pip list：查看当前环境已安装包
uv pip show ：查看包详情
uv python list：查看可用 Python

A.4 发布相关命令

uv export：导出锁文件到其他格式
uv build：构建包
uv publish：发布包

A.5 工作空间相关

uv add --package ：为指定成员包添加依赖
uv sync --package ：同步指定成员包
uv sync --all-packages：同步整个 workspace

附录B：配置文件参考

B.1 pyproject.toml 完整配置示例

结合本仓库现状，可参考：

[project]

name = "quant-local"
version = "0.1.0"
description = "本地量化数据分析 MVP 系统"
readme = "README.md"

requires-python = ">=3.13"

[project.scripts]

quant = "quant_local.cli:app"

[[tool.uv.index]]

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

[tool.uv]

dev-dependencies = [

"pytest>=8.0.0",

"pytest-cov>=4.0.0",

]

B.2 常用环境变量

UV_PROJECT_ENVIRONMENT

UV_PYTHON

UV_CACHE_DIR

UV_DEFAULT_INDEX

UV_INDEX

UV_LOCKED

UV_FROZEN

B.3 全局配置选项

优先级通常为：

命令行参数
项目配置文件
uv.toml
环境变量

具体行为以当前 uv 版本文档和帮助输出为准。

附录C：迁移指南

C.1 从 pip + virtualenv 迁移

推荐步骤：

补齐 pyproject.toml
用 uv add 或 uv pip install -r requirements.txt 导入依赖
生成 uv.lock
统一改用 uv run、uv sync

C.2 从 Poetry 迁移

保留原有 pyproject.toml
用 uv 在项目根目录重新解析并生成 uv.lock
对照原依赖组与脚本定义做兼容性检查

C.3 从 Pipenv 迁移

把 Pipfile 中的依赖迁入 pyproject.toml
使用 uv add --dev 重建开发依赖组
删除旧虚拟环境后重新 uv sync

C.4 从 Conda 迁移

区分 Python 依赖和非 Python 依赖
纯 Python 项目适合直接迁移到 uv
依赖大量系统库的项目需要评估是否保留 Conda 管理底层运行时

附录D：术语表

虚拟环境：隔离的 Python 运行环境
锁文件：记录精确依赖解析结果的文件，本手册中指 uv.lock
依赖组：开发、文档、测试等按用途划分的依赖集合
Workspace：单仓库多 Python 包协同开发结构
PEP 621：Python 项目元数据标准
PEP 723：脚本内联依赖元数据标准
ASGI：异步 Python Web 服务器接口标准，Uvicorn 属于此生态常用服务端

Python虚拟环境和包管理器uv使用手册

第1章：uv 简介

1.1 什么是uv

1.2 主要特性

1.3 与传统工具对比

1.3.1 vs pip + virtualenv 组合

1.3.2 vs Poetry

1.3.3 vs Pipenv

1.3.4 vs Conda

1.4 适用场景

第2章：安装指南

2.1 系统要求

2.2 安装方法

2.2.1 官方脚本安装（推荐）

2.2.2 包管理器安装

使用Homebrew安装（macOS）

For RHEL/CentOS

For Fedora

2.2.3 预编译二进制下载

2.3 安装验证

2.4 版本升级

升级到最新正式版

2.5 卸载方法

官方卸载脚本

第3章：快速上手

3.1 基本概念

3.1.1 虚拟环境

3.1.2 依赖锁文件（uv.lock）

3.1.3 pyproject.toml 配置文件

3.1.4 开发依赖 vs 生产依赖

3.2 第一个uv项目

3.2.1 项目初始化

3.2.2 安装第一个包

3.2.3 运行项目代码

3.3 现有项目迁移

3.3.1 从requirements.txt迁移

3.3.2 从Poetry/Pipenv项目迁移

3.3.3 现有虚拟环境导入

3.4 常用命令速览

第4章：虚拟环境管理

4.1 虚拟环境基础

4.1.1 虚拟环境的作用和优势

4.1.2 uv 的虚拟环境存储位置

4.1.3 虚拟环境的识别规则

4.2 创建虚拟环境

4.2.1 项目内虚拟环境

4.2.2 全局或命名虚拟环境

4.3 虚拟环境操作

4.3.1 激活虚拟环境

4.3.2 临时激活

4.3.3 查看虚拟环境信息

4.3.4 退出虚拟环境

4.4 虚拟环境管理

4.4.1 列出环境

4.4.2 删除虚拟环境

4.4.3 重建环境

4.5 高级配置

4.5.1 配置默认虚拟环境位置

4.5.2 Python 版本管理

4.5.3 Shell 集成

第5章：依赖包管理

5.1 依赖管理基础

5.1.1 依赖类型

5.1.2 版本约束语法

5.2 添加依赖

5.2.1 添加生产依赖

5.2.2 添加开发依赖

5.2.3 添加到指定依赖组

5.2.4 指定版本或版本策略

5.2.5 安装预发布版本

5.2.6 从 Git、本地路径安装

5.3 依赖查询

5.3.1 查看已安装依赖

5.3.2 查看单个包详情

5.3.3 查看依赖树

5.3.4 查询说明

5.4 更新依赖

5.4.1 更新所有依赖

5.4.2 更新指定包

5.4.3 仅更新锁文件