主要聊聊，进阶与企业最佳实践！
uv 是一个基于 Rust 实现的 Python 极速包管理器，用于替代 pip 和 virtualenv 的组合，主打 快、干净、易用。它是由 astral.sh 团队开发的，目标是让 Python 项目构建和依赖管理更现代化。
1. 创造原因
主要介绍
uv工具的主要优势！
uv 是由 Astral 公司开发的一个全新的 Python 包安装器和解析器，旨在成为 pip 和 pip-tools 的替代品。它用 Rust 编写，因此在性能上具有显著优势，尤其是在处理大型依赖图时。
> 1. 颠覆性优势
极速性能：uv 能够以比 pip 快 10-100 倍的速度安装和解析依赖。确定性构建：默认情况下，uv 会生成确定性的锁定文件，确保在不同环境中安装相同的依赖版本，从而提高可重复性。
统一工作流：uv 整合了 pip(安装)、pip-tools(编译依赖)和 venv(虚拟环境管理)的功能，提供了一个更统一、更简洁的命令行界面。兼容性：uv 旨在与现有的 pip 生态系统兼容，支持 requirements.txt 文件和 pyproject.toml 中的 [project] 表。
> 2. 企业级特性
此外，UV 内置 跨平台锁文件(uv.lock) 和 全局依赖缓存 机制，可共享缓存节省磁盘空间，并确保不同机器上安装结果一致。简而言之，UV 致力于为 Python 提供 更快、更可靠、更统一 的包管理体验，为项目开发带来新的选择。
# 企业级配置模板
# ~/.config/uv/config.toml
[install]
# 国内镜像加速
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
[cache]
# 全局缓存路径
path = "/opt/uv-cache"
[venv]
# 统一虚拟环境目录
path = "venv"
2. 安装方式
Python 相关工具安装都比较简单！
安装 uv 非常简单，可以从 PyPI 安装，也可以使用 pipx(推荐使用)。
# macOS/Linux
$ curl -LsSf https://astral.sh/uv/install.sh | sh
# From PyPI
$ pip install uv # pip
$ pipx install uv # pipx
# uv can update
$ uv self update
# check vesion
$ uv --version
3. 基本用法
用户可以快速上手，使用非常无感。
uv 旨在替代 pip-tools 的功能，因此 uv pip compile 和 uv pip sync 提供了与 pip-tools 类似的工作流。如果您之前使用 pip-tools，可以无缝切换到 uv。除了基本功能，uv 还提供了一些高级特性，可以进一步优化您的开发工作流。
> 1. 安装包：uv pip install
$ uv pip install requests
$ uv pip install "Django<4" "celery>=5.2"
> 2. 同步依赖：uv pip sync
它用于根据锁定文件(requirements.txt、requirements.lock)精确同步虚拟环境中的依赖，这类似于 pip install -r，但 uv 提供了更快的速度和更强的确定性。
$ uv pip sync requirements.txt
> 3. 编译依赖：uv pip compile
uv pip compile 类似于 pip-compile，用于根据抽象的依赖(pyproject.tml等)生成一个精确的锁定文件(requirements.txt、requirements.lock)。这个锁定文件包含了所有直接和间接依赖的精确版本。
$ uv pip compile pyproject.tml -o requirements.txt
$ uv pip compile requirements.in -o requirements.txt
4. 高级特性
整合 pip/virtualenv/poetry/pyenv 等 7 大工具功能
在 Python 生态系统中，依赖管理和包安装一直是开发者面临的挑战。传统的 pip 工具虽然功能强大，但在速度、依赖解析和可重复性方面仍有改进空间。近年来，一个新的工具 uv 横空出世，旨在解决这些痛点，并提供一个更快速、更可靠的 Python 包管理体验。
> 1. 替代 virtualenv 特性：虚拟环境管理(python -m venv)
UV 默认在项目目录下，创建并使用虚拟环境。与 pip 默认全局安装不同，执行 uv pip install 时会自动查找当前激活的虚拟环境或项目根目录的 .venv 并安装到其中。这确保了每个项目环境隔离，避免了版本冲突。注意：UV 要在系统环境中安装包需要使用 --system 参数或 UV_SYSTEM_PYTHON=1 开关。
# 初始化项目(创建虚拟环境/.venv)
$ uv venv
$ uv venv --python 3.14 # 指定版本
$ uv venv --seed # 强制安装基础包(pip/setuptools/wheel)
# 安装/升级/删除依赖
$ uv pip install flask
$ uv pip install -U flask
$ uv pip uninstall flask
# 查看更新包
$ uv pip list --outdated
# 激活虚拟环境(与传统方式相同)
$ source .venv/bin/activate
# 退出虚拟环境(与传统方式相同)
$ deactivate
> 2. 使用 uv + pyproject.toml 组合安装依赖
uv 完全支持 pyproject.toml 文件中定义的 [project] 表，用于声明项目的直接依赖。这使得 uv 能够更好地与现代 Python 项目结构集成。
# 使用现代Python项目结构
$ cat pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
dependencies = [
"requests",
"Django",
]
# 如果当前目录有pyproject.toml文件
$ uv pip compile pyproject.toml -o requirements.txt
$ uv pip sync requirements.lock
# 运行脚本
$ uv run .\example.py
> 3. 替代 poetry 特性：项目管理与锁定文件
UV 支持在 pyproject.toml 中声明依赖，也兼容 requirements.txt、setup.py 等格式。使用 uv add <包名> 可将新依赖添加到 pyproject.toml 并自动更新锁文件和环境；使用 uv remove <包名> 可将依赖移除。对于老项目，还可通过 uv add -r x.txt 一次性导入所有依赖。
# 初始化项目
$ uv init hello-world
$ uv init hello-world --python 3.14
# 管理依赖
$ cd hello-world
$ uv add 'requests==2.31.0' # 添加生产依赖
$ uv add pytest --dev # 添加开发依赖
$ uv lock --upgrade-package requests # 更新项目依赖
$ uv remove requests # 删除项目依赖
# 显示项目的依赖项树
$ uv tree --outdated
$ uv tree --depth 2
支持在 pyproject.toml 中的 [tool.uv.index] 配置项里添加自定义索引，比如内部 PyPI 镜像、Azure Artifacts 等等。需要注意的是，与 pip 不同，UV 默认不会自动混用多个索引。如果需要使用镜像源，必须显式配置索引地址，并可通过环境变量或 keyring 插件来指定凭证。
# 项目结构
.
├── .git
├── .gitignore
├── .venv
├── .python-version
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock
# 运行项目脚本
$ uv run main.py
> 4. 替代 pipx 特性：管理全局 CLI 工具
UV 内置对可执行脚本和基于 Python 的 CLI 工具支持，可像运行系统命令一样使用 uv run <脚本> 来执行项目脚本。
# 全局安装black代码格式化工具(类似于pipx)
$ uv tool install black
# 运行全局工具
$ uv tool run black ./myfile.py
# 同时提供更易用的uvx命令(类似于npx)
$ uvx pycowsay 'hello world!'
$ uvx ruff format ./myscript.py
> 5. 替代 pyenv 特性：解决 Python 版本管理
# 查看已安装和可安装的Python版本
$ uv python list
# 安装指定Python版本
$ uv python install 3.13.2
# 使用特定版本运行脚本
$ uvx [email protected] -c "print('hello world')"
> 6. 离线安装和缓存管理
离线安装：uv 支持离线安装，这对于在没有互联网连接的环境中部署应用程序非常有用。你可以先将所有依赖下载到本地缓存，然后从缓存进行安装。首先，确保所有依赖都已下载到 uv 的缓存中(通常在 $HOME/.cache/uv 目录)。然后，在离线环境中，您可以指定 uv 只从缓存中安装。
# 这会将它们下载到缓存
$ uv pip install requests Django
# 可以指定uv只从缓存中安装
$ uv pip sync requirements.lock --offline
> 7. 缓存管理：uv 会自动缓存下载的包，以加速后续的安装。
缓存优化策略，实测可减少 60% 的 CI/CD 网络流量。
# 查看缓存位置
$ uv cache dir
# 清理缓存
$ uv cache clean
# 预热全局缓存(适用于Docker基础镜像构建)
$ uv cache warmup -r requirements.txt
# 清理无效缓存
$ uv cache purge --older-than 30d
# 共享缓存目录(Kubernetes场景)
$ docker run -v /shared/uv-cache:/cache my-app
5. 最佳实践
uv的特性使其成为企业级 Python 项目的理想选择！
> 1. 可重复构建
最重要的企业级特性之一，通过 uv pip compile 生成的锁定文件(requirements.lock)，可以确保在任何环境中，只要使用相同的锁定文件，就能安装完全相同的依赖版本。
始终使用锁定文件：提交 requirements.lock 或类似名称到版本控制系统；开发与生产环境分离：维护不同的 requirements.in 文件区分版本，并编译生成对应的锁定文件；自动化编译：在 CI/CD 管道中自动化 uv pip compile 步骤，确保锁定文件始终是最新的。
> 2. 安全性考量
企业项目通常有严格的安全要求，需要对所有依赖进行审计，以识别潜在的漏洞。
定期更新依赖：使用 uv pip compile --upgrade 定期更新锁定文件，以获取最新的安全补丁；集成漏洞扫描工具：将 uv 生成的锁定文件与 Snyk、Dependabot 或 Trivy 等漏洞扫描工具集成，自动检测已知漏洞；私有包源：对于内部包，使用 uv --extra-index-url 或在 pip.conf 中配置私有 PyPI 源。
> 3. 与 CI/CD 的集成
uv 的速度优势在 CI/CD 管道中尤为明显，可以显著缩短构建和部署时间。
缓存 uv 缓存目录：在 CI/CD 管道中缓存 uv 的缓存目录(通常是 ~/.cache/uv)，以避免重复下载依赖；使用 uv pip sync：在构建步骤中使用 uv pip sync 来精确安装依赖；容器化：在 Docker 镜像构建过程中使用 uv，确保镜像中包含精确的依赖版本。
6. 实战案例
一个中型项目的 UV 流程！
> 1. 初始化项目
使用 uv init 命令创建新项目骨架，该命令会生成 .python-version、README.md、main.py、pyproject.toml 等文件。
# 普通使用方式(创建单包项目)
$ uv init mywebapp --python 3.14
$ cd mywebapp
# 与主流框架整合(FastAPI项目模板；创建多包工作区项目)
$ uv project init --template=fastapi my-api
$ uv add "uv[fastapi]"
$ uv run --reload
> 2. 添加依赖
编辑 pyproject.toml 或使用 uv add 命令添加运行时和开发依赖。uv add 会自动更新 pyproject.toml 的 dependencies/optional-dependencies 和锁文件，并安装到环境。
$ uv add flask gunicorn # 添加生产依赖
$ uv add pytest --dev # 添加开发依赖
> 3. 创建虚拟环境
第一次运行与依赖相关的命令时，UV 会自动在项目根目录生成 .venv 目录(包含完整虚拟环境)。此后，UV 会在该环境中安装和运行代码，无需手动激活。
# 创建Python3.8兼容环境
$ uv venv --python=3.8 .venv-38
# 激活指定环境
$ source .venv-38/bin/activate
> 4. 锁定依赖
运行锁定命令生成 uv.lock，这会根据当前的 pyproject.toml，解析并记录所有依赖的确切版本到 uv.lock。
$ uv lock
> 5. 安装测试
团队成员拉取项目后，只需执行如下命令，即可快速重现相同环境。若项目中有运行或测试脚本，可使用 uv run 执行。
# 同步安装uv.lock中锁定的依赖
$ uv sync
$ uv pip install -r uv.lock
> 6. 日常开发
后续若需要新增依赖，重复使用 uv add，并运行 uv lock 更新锁文件。CI/CD 环境通常只需拉取代码并执行 uv sync，即可自动获取所有新依赖。
# 依赖来源管控(uv.toml/pyproject.toml)
[install]
allowed-sources = [
"https://pypi.private.com/simple", # 私有制品库
"https://pypi.org/simple", # 受监控的公共源
"https://mirror.trusted.cn/simple" # 经过审计的镜像源
]
# 签名验证(安装时强制校验哈希)
$ uv pip install --require-hashes -r requirements.txt
# 签名验证(生成带哈希的锁定文件)
$ uv pip compile --generate-hashes > requirements.lock
# 审计流程
$ uv pip audit --json > audit.log
$ uv pip audit --cve-id CVE-2024-1234 --verbose # 定向漏洞排查
# 镜像同步(创建企业镜像)
$ uv mirror create --name corp-mirror \
--upstream https://pypi.org/simple \
--storage s3://corp-pypi-mirror \
--schedule "0 2 * * *" # 每日凌晨同步
# 镜像同步(客户端配置)
$ uv config set install.index-url="https://mirror.corp.com/simple"
7. 总结展望
UV 的最大优势在于 速度快、功能全、体验统一！
uv 是 Python 包管理领域的一个令人兴奋的新工具。其卓越的性能、统一的工作流和对确定性构建的强调，使其成为现代 Python 项目的强大资产。无论您是个人开发者还是企业团队，uv 都能帮助您更高效、更可靠地管理 Python 依赖。
