uv包管理工具 - 技术栈

uv包管理工具笔记

1 介绍

uv 是一款用 Rust 编写的高性能 Python 包和项目管理工具，旨在为开发者提供一体化的开发环境管理方案，可替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多个工具。

其核心优势包括：

极致速度 ：依赖解析和包安装速度比 pip 快 10-100 倍（基于官方基准测试），得益于 Rust 语言的高效性能。
功能集成：集虚拟环境管理、依赖安装与锁定、Python 版本管理、工具临时运行等功能于一体。
兼容性强 ：提供与 pip 兼容的接口（如 uv pip install），可无缝迁移现有工作流。
跨平台支持：适配 macOS、Linux、Windows 系统，且支持 Docker 等容器环境。
现代工作流 ：支持 PEP 标准项目结构、依赖锁文件（uv.lock）、工作区管理等现代开发模式。

2 安装

uv 提供多种安装方式，可根据系统和场景选择：

2.1 独立安装器（推荐）

macOS/Linux：

bash 复制代码

# 安装最新版本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装指定版本（如 0.9.17）
curl -LsSf https://astral.sh/uv/0.9.17/install.sh | sh

若系统无 curl，可替换为 wget：

bash 复制代码

wget -qO- https://astral.sh/uv/install.sh | sh

Windows（PowerShell）：

powershell 复制代码

# 安装最新版本
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 安装指定版本（如 0.9.17）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.9.17/install.ps1 | iex"

2.2 从 PyPI 安装

适合已安装 Python 环境的场景，建议用 pipx 隔离：

bash 复制代码

# 用 pipx 安装（推荐）
pipx install uv

# 用 pip 安装（可能影响全局环境）
pip install uv

2.3 Docker 环境安装

在 Docker 中集成 uv 可通过两种方式：

dockerfile 复制代码

# 方式 1：从官方镜像复制二进制文件（推荐，体积小）
FROM python:3.12-slim-trixie
COPY --from=ghcr.io/astral-sh/uv:0.9.17 /uv /uvx /bin/

# 方式 2：通过安装脚本
FROM python:3.12-slim-trixie
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates
ADD https://astral.sh/uv/0.9.17/install.sh /uv-installer.sh
RUN sh /uv-installer.sh && rm /uv-installer.sh
ENV PATH="/root/.local/bin/:$PATH"

2.4 手动下载安装

以Windows11操作系统为例：

从 GitHub 下载对应平台的压缩包，解压后得到 uv.exe、uvw.exe、uvx.exe，将文件路径添加到系统环境变量 PATH 即可。

验证安装

安装完成后，运行以下命令确认：

bash 复制代码

uv --version  # 输出版本信息即表示成功

3 配置镜像源

uv 支持配置国内镜像源以提升下载速度，推荐使用阿里云、豆瓣、中科大等稳定源：

3.1 临时指定索引（单次命令）

通过 --index-url 参数临时使用镜像源：（以安装flask为例）

bash 复制代码

# 阿里云镜像
uv pip install flask --index-url https://mirrors.aliyun.com/pypi/simple/
uv add flask --index-url https://mirrors.aliyun.com/pypi/simple/

# 豆瓣镜像
uv pip install flask --index-url https://pypi.doubanio.com/simple/
uv add flask --index-url https://pypi.doubanio.com/simple/

# 中科大镜像
uv pip install flask --index-url https://pypi.mirrors.ustc.edu.cn/simple/
uv add flask --index-url https://pypi.mirrors.ustc.edu.cn/simple/

3.2 全局配置镜像源

通过环境变量或配置文件设置全局默认镜像：

方式1：环境变量

bash 复制代码

# macOS/Linux
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

# Windows PowerShell
# 当前终端
$env:UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"

# 或永久生效
[Environment]::SetEnvironmentVariable("UV_INDEX_URL", "https://mirrors.aliyun.com/pypi/simple/", "User")

方式2：配置文件

在用户配置目录创建 uv.toml 文件：

Linux/macOS: ~/.config/uv/uv.toml
Windows: %APPDATA%\uv\uv.toml

bash 复制代码

# uv.toml文件
index-url = "https://mirrors.aliyun.com/pypi/simple/"

3.3 项目级配置（推荐）

在项目根目录的 pyproject.toml 中配置，仅对当前项目生效：
[[tool.uv.index]] - 现代多索引配置

bash 复制代码

# 现代 uv 工作流推荐（影响 uv add/sync/run）
# 定义主索引（豆瓣）
[[tool.uv.index]]
url = "https://pypi.doubanio.com/simple/"
default = true  # 标记为默认主索引

# 定义备用索引（阿里云）
[[tool.uv.index]]
url = "https://mirrors.aliyun.com/pypi/simple/"

# 定义专用索引
# 专用索引1：pytorch-cpu
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu/"
explicit = true  # 只有指定 name 的包才会使用

# 专用索引2：私有 GitLab 源
[[tool.uv.index]]
name = "gitlab-private"
url = "https://gitlab.example.com/api/v4/projects/123/packages/pypi/simple"
explicit = true

# --- 关键部分：将包映射到对应的索引 ---
[tool.uv.sources]
# 格式：包名 = [{ index = "索引名" }]
# [tool.uv.sources] 中的包名必须匹配 project.dependencies 中的名称
torch = [{ index = "pytorch-cpu" }]
private-package = [{ index = "gitlab-private" }]

配置优先级：项目级配置（pyproject.toml） > 环境变量 > 用户级配置（uv.toml）

3.5 验证配置

查看当前生效的镜像源：

查看当前项目的 pyproject.toml 中是否有 [tool.uv.pip] 配置段，镜像源信息会在此处定义：

bash 复制代码

# 方法1：查看环境变量
echo $UV_INDEX_URL  # Linux/macOS
echo $env:UV_INDEX_URL  # Windows PowerShell

# 方法2：查看完整配置（包括所有来源）
uv run --show-settings

注意：一般情况下，uv的cache目录会有默认缓存路径：

复制代码

Linux: $HOME/.cache/uv
macOS: /Users/<user>/Library/Caches/uv
Windows: %LOCALAPPDATA%\uv\cache（通常是 C:\Users\<用户>\AppData\Local\uv\cache）

如果要修改缓存存放路径，可通过以下方式进行修改------------

base 复制代码

# Linux/macOS
export UV_CACHE_DIR=/path/to/your/cache/dir

# Windows（通过系统环境变量设置）
# 新建系统变量 UV_CACHE_DIR，值为 D:\uv_cache 等路径

以Windows为例：

验证：uv cache dir

清空缓存

复制代码

清理未使用的缓存：uv cache prune（删除无用包后释放空间）
彻底清空缓存：uv cache clean（删除整个缓存目录）

还有，更重要的一点是，uv也有默认的存放python解释器的路径，
它会将下载的python解释器默认存放到这个目录中：C:\Users\用户\AppData\Roaming\uv\python

所以，如果你想删除某个项目，或某个虚拟环境，所对应的python解释器是不会被删除的，因为虚拟环境引用的是其快捷方式，这恰恰揭示了 uv 高效缓存机制的核心设计！

因此，如果你想修改uv默认存放python解释器的路径，可以这么做------------

之后，uv所下载安装的python解释器，就会存放在你指定的目录中
可通过 uv python list 验证

4 创建Python项目（基于虚拟环境）

uv 提供简洁的项目初始化与虚拟环境管理流程，步骤如下：

4.1 初始化项目

在空目录中创建项目结构（生成 pyproject.toml 等文件）：

bash 复制代码

# 方式一: 基本初始化（默认Python版本）
uv init my_project
cd my_project

# 方式二: 指定Python版本初始化（如3.12）
uv init my_project --python 3.12
cd my_project

4.2 创建并激活虚拟环境

bash 复制代码

# 方式一: 在项目目录中创建虚拟环境（默认路径为 .venv）
uv venv
# 方式二: 自定义虚拟环境名
uv venv 虚拟环境名

# 激活环境（以默认虚拟环境名为例）
# macOS/Linux
source .venv/bin/activate

# Windows
# PowerShell
.venv\Scripts\Activate.ps1
# CMD 命令提示符
.venv\Scripts\activate.bat
# Git Bash / WSL
source .venv/Scripts/activate

4.3 添加依赖

bash 复制代码

# 添加生产依赖（自动更新 pyproject.toml 和 uv.lock）
uv add flask  # 最新版本
uv add "requests>=2.31.0"  # 指定版本约束
uv add "git+https://github.com/astral-sh/ruff"  # 从Git仓库添加

# 添加开发依赖（仅开发环境使用）
uv add --dev pytest  # 测试工具
uv add --dev black  # 代码格式化工具

小细节1：

复制代码

通常情况下，在初始化项目的命令中，我们推荐采用上述方式二：uv init my_project --python 3.12
然而，虽然方式二指定了python解释器的版本，但是执行该命令后却不会立马进行下载安装该解释器

当执行该命令，uv会做以下两件事：
	1. 创建项目结构：生成 pyproject.toml、.python-version 等文件
	2. 记录版本要求：在 .python-version 文件中写入 3.12，作为项目的 Python 版本约束
	
因为，uv 采用惰性下载（lazy downloading）策略，只有当你执行需要实际使用 Python 解释器的命令时，才会检查并下载

小细节2：

复制代码

有时候，我们会看到另一种写法：
	uv init my_project 			【初始化项目不指定python解释器版本】
	cd my_project
	uv venv --python 3.12		【在创建虚拟环境时指定python解释器版本】
	.venv\Scripts\Activate.ps1

那么，pyproject.toml 无版本记录，约束仅生效一次，所以是不大推荐的

因此，我们更倾向于方式二的写法

小细节3：

复制代码

如果，我们不指定python解释器的版本【uv init命令中不指定，uv venv命令中也不指定】
那么，最终会采用内置的 fallback 版本（如 uv 0.9.17 的Python 版本为3.12）

4.4 将创建好的项目在PyCharm中打开

4.4.1 File -- > Open -- > 项目名

4.4.2 配置环境变量中的解释器

4.4.3 打开PyCharm终端验证是否已激活对应的虚拟环境

4.5 生成依赖锁文件

基于 pyproject.toml 生成锁定文件（确保依赖版本一致）：

bash 复制代码

uv lock

手动锁定，生成的 uv.lock 记录了所有依赖的精确版本，适合团队协作和部署。
一般情况下，uv add命令会自动更新 pyproject.toml 和 uv.lock

4.6 同步环境

根据锁文件安装依赖到虚拟环境（确保环境一致性）：

如果锁文件与 pyproject.toml 不一致则报错

bash 复制代码

uv sync --locked  # 严格按照锁文件安装

4.7 运行项目

通过 uv run 在虚拟环境中运行脚本或命令：

bash 复制代码

# 运行Python脚本
uv run main.py

# 运行安装的工具（如pytest）
uv run pytest tests/

5 其他常见命令

5.1 包管理（兼容 pip 接口）

安装指定版本： uv pip install "flask==2.3.3"
卸载包： uv pip uninstall flask
冻结依赖（生成 requirements.txt）： uv pip freeze > requirements.txt
同步 requirements.txt： uv pip sync requirements.txt
编译依赖（从 .in 文件生成 .txt）： uv pip compile requirements.in --output requirements.txt

5.2 项目管理

移除依赖： uv remove flask（从 pyproject.toml 中移除）
查看依赖树： uv tree（展示项目依赖关系）
格式化代码： uv run ruff format .（需先添加 ruff/black 等工具）
构建包： uv build（生成 sdist 和 wheel 包）
发布包： uv publish（上传到 PyPI 或指定索引）

5.3 工具运行（类似 pipx）

临时运行工具（无需安装）： uvx black --version（直接运行 black）
安装工具到用户目录： uv tool install ruff（全局可用，不污染项目环境）

5.4 Python 版本管理

安装指定 Python 版本： uv python install 3.11 3.12
锁定当前目录 Python 版本： uv python pin 3.11（生成 .python-version 文件）
查看已安装版本： uv python list

5.5 查看当前项目安装了哪些包

命令	适用场景	显示内容	优点	缺点
`uv pip list`	传统 pip 工作流	包名和版本	简单直接，支持 `--outdated`	不显示依赖关系
`uv tree`	现代项目工作流	依赖树结构	清晰展示依赖关系	需 pyproject.toml
`uv.lock`	精确版本核查	精确锁定版本和哈希	最精确，适合CI/CD	可读性较差
`uv pip freeze`	环境导出	requirements 格式	兼容 pip 生态	不显示间接依赖

6 与 pip、conda、pdm 工具的对比

特性	uv	pip	conda	pdm
核心定位	全功能 Python 包/项目管理器	基础 Python 包安装工具	跨语言包/环境管理器（支持 Python、C++ 等）	现代 Python 项目管理器（PEP 621 支持）
速度	极快（Rust 实现，10-100x 于 pip）	较慢（Python 实现）	中等（依赖解析复杂）	较快（Rust 优化部分逻辑）
虚拟环境	原生支持（`uv venv`）	依赖 `venv` 或 `virtualenv`	原生支持（环境隔离性强）	原生支持（`pdm venv`）
依赖锁定	支持（`uv.lock`，平台无关）	需配合 `pip-tools` 生成 `requirements.txt`	支持（`environment.yml`）	支持（`pdm.lock`）
Python 版本管理	原生支持（`uv python`）	不支持（依赖 `pyenv` 等工具）	原生支持（`conda install python=3.11`）	需配合 `pyenv` 等工具
多语言支持	仅 Python	仅 Python	支持（Python、R、C++ 等）	仅 Python
兼容性	兼容 pip 接口（`uv pip`）	标准接口，生态最广	部分 Python 包需适配 conda 渠道	兼容 pip 包，支持 PEP 标准
适用场景	追求速度和一体化管理的 Python 项目	简单包安装、脚本依赖	多语言项目、科学计算（依赖 C 库）	现代 Python 项目（PEP 621 优先）

总结：
uv

适合需要高效依赖管理、替代多工具（如同时需要 pip、pipx、pyenv）的 Python 开发者，尤其在大型项目中能显著提升效率；
conda

更适合跨语言或依赖复杂系统库的场景（如科学计算）；
pdm

专注于 Python 现代项目规范（如 PEP 621），适合追求标准化的团队；
pip

仍是最基础的包安装工具，适合简单脚本或快速验证场景。