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：
# 安装最新版本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：wget-qO- https://astral.sh/uv/install.sh|shWindows（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隔离：
# 用 pipx 安装（推荐）pipxinstalluv# 用 pip 安装（可能影响全局环境）pipinstalluv2.3 Docker 环境安装
在 Docker 中集成 uv 可通过两种方式：
# 方式 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 即可。
验证安装
安装完成后，运行以下命令确认：
uv --version# 输出版本信息即表示成功3 配置镜像源
uv 支持配置国内镜像源以提升下载速度，推荐使用阿里云、豆瓣、中科大等稳定源：
3.1 临时指定索引（单次命令）
通过--index-url参数临时使用镜像源：（以安装flask为例）
# 阿里云镜像uv pipinstallflask --index-url https://mirrors.aliyun.com/pypi/simple/ uvaddflask --index-url https://mirrors.aliyun.com/pypi/simple/# 豆瓣镜像uv pipinstallflask --index-url https://pypi.doubanio.com/simple/ uvaddflask --index-url https://pypi.doubanio.com/simple/# 中科大镜像uv pipinstallflask --index-url https://pypi.mirrors.ustc.edu.cn/simple/ uvaddflask --index-url https://pypi.mirrors.ustc.edu.cn/simple/3.2 全局配置镜像源
通过环境变量或配置文件设置全局默认镜像：
方式1：环境变量
# macOS/LinuxexportUV_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
# uv.toml文件index-url="https://mirrors.aliyun.com/pypi/simple/"3.3 项目级配置（推荐）
在项目根目录的pyproject.toml中配置，仅对当前项目生效：[[tool.uv.index]] - 现代多索引配置
# 现代 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] 配置段，镜像源信息会在此处定义：
# 方法1：查看环境变量echo$UV_INDEX_URL# Linux/macOSecho$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） 如果要修改缓存存放路径，可通过以下方式进行修改————# 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等文件）：
# 方式一: 基本初始化（默认Python版本）uv init my_projectcdmy_project# 方式二: 指定Python版本初始化（如3.12）uv init my_project --python3.12cdmy_project4.2 创建并激活虚拟环境
# 方式一: 在项目目录中创建虚拟环境（默认路径为 .venv）uv venv# 方式二: 自定义虚拟环境名uv venv 虚拟环境名# 激活环境（以默认虚拟环境名为例）# macOS/Linuxsource.venv/bin/activate# Windows# PowerShell.venv\Scripts\Activate.ps1# CMD 命令提示符.venv\Scripts\activate.bat# Git Bash / WSLsource.venv/Scripts/activate4.3 添加依赖
# 添加生产依赖（自动更新 pyproject.toml 和 uv.lock）uvaddflask# 最新版本uvadd"requests>=2.31.0"# 指定版本约束uvadd"git+https://github.com/astral-sh/ruff"# 从Git仓库添加# 添加开发依赖（仅开发环境使用）uvadd--dev pytest# 测试工具uvadd--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生成锁定文件（确保依赖版本一致）：
uv lock手动锁定，生成的uv.lock记录了所有依赖的精确版本，适合团队协作和部署。一般情况下，uv add命令会自动更新 pyproject.toml 和 uv.lock
4.6 同步环境
根据锁文件安装依赖到虚拟环境（确保环境一致性）：
如果锁文件与 pyproject.toml 不一致则报错
uvsync--locked# 严格按照锁文件安装4.7 运行项目
通过uv run在虚拟环境中运行脚本或命令：
# 运行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
仍是最基础的包安装工具，适合简单脚本或快速验证场景。
