[Python/依赖管理] UV : Python 包与环境管理工具

0 序

• 学习一款新的Python依赖包管理与环境管理工具: UV。

"最近几个月，我注意到一个现象：看到的新开源项目里，越来越多开始在README里写uv pip install而不是pip install。"

2025年，Python包管理工具已经由pip变成了uv？ - Weixin/机器学习实验室 2025.11.13
全文主要摘自此篇。

比如最近与Kimi K2 Thinking一起发布的Kimi CLI就是通过uv命令安装的：

uv tool install --python 3.13 kimi-cli

• 在 Python 开发中，包管理和环境隔离是每个开发者都会遇到的问题。

无论是 pip 的缓慢、virtualenv 的繁琐，还是 conda 的臃肿，都让开发者们期待一个更高效的解决方案。

1 概述: UV := Universal Virtual := Python 包与环境管理工具

uv是什么?

• uv (Universal Virtual) 是 Astral 公司开发了一款新的Python包管理工具。

提到Astral，你可能会想起他们去年发布的Ruff。
那个用Rust写的Python linter，速度快到离谱，现在已经是很多项目的标配。

• uv目前在Github斩获73k的star。

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

• Slogan :

An extremely fast Python package and project manager, written in Rust.
一款用Rust编写的、非常快的Python包和项目管理器。

• 2024 年 2 月首次发布，当时的定位是更快的pip。几个月后，功能大幅扩展，变成了一个统一的Python工具链。

• 现在的uv，官方说可以替代pip、pip-tools、pipx、poetry、pyenv、virtualenv这一堆工具。

性能实测：快得离谱

• 先说性能，这是uv最吸引人的地方。

官方说uv比pip快10-100倍。一开始有大佬觉得这数字有点夸张，但看了一些真实案例后，确实差不多。

• 典型案例: 2024年4月，Streamlit把所有用户的包管理从pip切换到了uv。

结果是什么？
平均依赖安装时间从60秒降到了20秒，应用部署时间直接提升了55%。
这不是实验室数据，是真实的生产环境，每天数万个应用在跑。

• 包安装速度对比（无缓存）：

• 安装pandas：1.22s (uv) vs 2.62s (pip) - 快 53%
• 安装numpy + scipy + torch：3.5s (uv) vs 14.8s (pip) - 快 4.2 倍
• 解析50+ 包的requirements.txt：5.1s (uv) vs 28.4s (pip) - 快 5.6 倍

• 有缓存的情况下：

• Jupyter Notebook项目解析：0.57s（冷启动）→ 0.02s（温缓存）

这个速度提升就是几十倍到上百倍了

• 虚拟环境创建：

• uv创建虚拟环境比python -m venv快80倍

比virtualenv快7倍

• 除了速度快，【资源占用】也更少：

CPU 使用：68% (uv) vs 92% (pip)
内存占用：210MB (uv) vs 450MB (pip)

这意味着，在CI/CD环境或者【资源受限】的机器上，uv的优势会更明显。

为什么性能这么快?

看到这些数据，你可能会好奇：uv凭啥这么快？

• 首先，编程语言。

pip是用Python写的，uv用的是Rust。Rust是系统级编程语言，性能接近 C/C++。
这是基础性能差异。

• 其次，uv充分利用了Rust的并发特性。

传统的pip在下载和安装包时，大部分操作是串行的; 而uv可以同时处理多个依赖的下载、构建和安装。
在依赖树比较复杂的项目里，这种【并发处理】带来的提升非常明显。

• 此外，uv还有一个【全局模块缓存系统】。

当你第一次安装一个包后，uv会把它缓存起来。
下次再安装同样的包（可能是在不同的项目里），uv直接从缓存读取，甚至不需要重新下载。

• 而且在支持的文件系统上，uv使用【写时复制】（Copy-on-Write）和【硬链接】技术。

这意味着，同一个包在多个【虚拟环境】中共享，不会占用多倍的【磁盘空间】。

• 最后是，依赖解析算法。

依赖解析是【包管理】中最复杂的部分。
uv使用了【更高效的算法】来解析【依赖图】，支持平台无关的解析，还能生成跨平台的【锁文件】。
这不只是快，还更可靠。

不只是快：功能全面

• 【速度】，只是uv的一个卖点。让人更感兴趣的是，它想成为一个【全能工具】。
• 最基础的功能：uv可以完全替代pip

# 传统方式
pip install requests

# uv方式
uv pip install requests

• 命令几乎一样，学习成本很低。
• 而且uv还支持很多pip没有的高级特性，比如依赖版本覆盖、更灵活的解析策略等。

• 首先，uv可以像Poetry一样管理整个项目：

# 初始化项目
uv init my-project

# 运行项目
uv run main.py
又例如:
  uv run dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml
  或(跳过"运行前同步依赖(project sync)"这一步): uv run --no-sync dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml


# 生成跨平台锁文件
uv lock

# 同步环境
uv sync

生成的lockfile，确保团队成员和CI环境都用完全相同的依赖版本。

• uv也可以用于Python的版本管理（替代 pyenv），这个功能让我挺意外的：

# 安装 Python 3.12
uv python install 3.12

# 在当前目录下使用特定版本
uv python pin 3.12

• uv可以直接下载和管理Python版本，不需要额外装pyenv或 pythonbrew。
• uv也可以用于工具管理（替代 pipx），比如说需要安装一个【全局命令行工具】？

# 安装工具
uv tool install ruff

# 或一次性运行，不安装
uvx ruff check .

uvx这个命令特别方便，想临时用一个工具的时候，不需要先装到全局环境。

• uv还支持单文件Python脚本的依赖管理。

你可以在脚本开头声明依赖，然后用uv run script.py直接运行，uv会自动处理依赖安装和环境隔离。
这对写一些小工具脚本非常友好。

uv 的优势

• 速度极速：由于使用 Rust 编写，uv 的性能远超 pip 和其他包管理工具，安装依赖的速度可以提升 10-100 倍。

• 比 pip 快 10-100 倍，比 Conda 快 100 倍以上。

• 功能集成/一体化功能：集成虚拟环境管理、依赖锁定、Python 版本控制等。

集成语法分析、依赖解析、包安装、环境管理和 Python 版本管理于一体，无需再安装和学习多个工具。

• 确定性构建：uv 会生成 uv.lock 文件，确保在任何环境中都能安装完全相同的依赖版本，避免 "在我机器上能运行" 的问题。

• 与现有工具兼容：uv 可以处理 requirements.txt 和 pyproject.toml，可以无缝替代现有工作流中的 pip。

兼容 pip、requirements.txt 和 pyproject.toml。

• 跨平台支持：兼容 Windows、macOS 和 Linux。
• 零依赖：单文件二进制，无需额外安装 Python 环境。

uv能不能替代Conda / Pip?

• 这取决于使用场景：

• uv专注于Python依赖包管理，对于纯Python项目，它完全够用，而且更快更轻量。
• 但Conda可以管理【系统级依赖】（比如：CUDA、各种C库），在科学计算和深度学习领域，Conda还是有它的生态位置。

• 另外，有些CI平台对uv的支持还在完善中，可能需要自己写一点额外的配置。
• 偶尔会遇到一些包的构建问题，特别是那些有C扩展的老包。

不过这种情况不多，而且一般切回pip就能解决。

• 推荐做法：纯Python项目用uv，需要系统依赖的项目（比如 PyTorch GPU 版）还是用pip或者Conda。

• 应该对这些新的工具保持一点耐心，也许未来上述这种场景也将会被弥补上来。

"这就像你的Vibe Coding工具，在没用Claude Code之前，你用其他工具觉得非常好用。但是一旦用了Claude Code之后，就很难再用回其他工具。"

2 安装使用篇

说了这么多，不如亲自试一试。

2.0 安装 UV

• uv不需要预先安装Python和Rust，安装脚本会处理所有依赖。

2.0.1 安装 on MacOS/Linux

brew install uv

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

2.0.2 安装 on Windows | 全局安装（推荐 / 笔者的选择）

特点：所有 conda 环境都可以调用这个 uv，不会随 conda 环境删除而删除，绝大多数人的使用方式。
即使全局安装 uv，uv 也能自动识别已激活的 conda 环境 (CONDA_PREFIX)，向 conda 环境安装包：uv pip install xxx，不需要把 uv 装到 conda 的虚拟环境内部

• CMD or PowerShell 窗口:

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

安装日志:

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

To add C:\Users\EDY\.local\bin to your PATH, either restart your shell or run: (为了便于基于 uv 命令便捷/快速地使用，可自行配置 PATH 环境变量 或执行:)

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

安装完成后，按提示将UV添加到系统PATH(Linux: 默认路径：~/.local/bin 或 $HOME/.cargo/bin)

• 完整示例(powershell):

//打开窗口1:
PS F:\Codes-Minor\Github> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
downloading uv 0.12.10 (x86_64-pc-windows-msvc)
installing to C:\Users\Johnny\.local\bin
  uv.exe
  uvx.exe
  uvw.exe
everything's installed!

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

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


//新开窗口2:
PS F:\Codes-Minor\Github> uv --version
uv 0.12.10 (3c979abda 2026-09-04 x86_64-pc-windows-msvc)
PS F:\Codes-Minor\Github> where.exe uv
C:\Users\xxx\.local\bin\uv.exe

• 补充：python 的 uv 安装的python包默认是在哪个路径？能否将该C盘的路径修改为别的磁盘盘符？（避免Windows的C盘存储空间膨胀） => 参见本文档 FAQ 章节。（建议执行）

2.0.3 安装 on Windows | 基于conda的Python虚拟环境安装uv

• 激活 conda 环境后，用环境内的 pip 安装，uv 会落在该 env 的Scripts/bin目录下

conda activate my_env
pip install uv

• 验证是否真的装在当前 conda 环境

# Linux/macOS
which uv

# Windows PowerShell
where.exe uv
例如:
(python-3.13) PS F:\Codes-Minor\Github> where.exe uv
C:\Users\xxx\.conda\envs\python-3.13\Scripts\uv.exe

输出路径前缀应当等于环境变量$CONDA_PREFIX，代表 uv 属于当前 conda 环境；
如果输出是~/.local/bin/uv，那是全局二进制版本，不是 conda 环境内的。

2.1 卸载 UV

2.1.1 卸载 on Windows by Powershell（尤指全局安装UV）

• step1 先确认 uv 的程序位置，获得 UV 的 Source 路径

Get-Command uv

情况1: 二进制放在 $HOME\.local\bin，则不属于 conda 环境
情况2: 二进制放在 conda 的 python 虚拟环境下（如: $HOME\.conda\envs\python-3.13\Scripts\uv.exe 即 C:\Users\xxx\.conda\envs\python-3.13\Scripts\uv.exe），则属于 conda 环境
...

• step2 基于 UV 路径 删除二进制（PowerShell）

假设 二进制放在 $HOME\.local\bin 下

# 删除主程序
Remove-Item $HOME\.local\bin\uv.exe -ErrorAction SilentlyContinue
Remove-Item $HOME\.local\bin\uvx.exe -ErrorAction SilentlyContinue
Remove-Item $HOME\.local\bin\uvw.exe -ErrorAction SilentlyContinue

# 旧版本(<0.5.0)安装在 ~\.cargo\bin，一并清理
Remove-Item $HOME\.cargo\bin\uv.exe -ErrorAction SilentlyContinue
Remove-Item $HOME\.cargo\bin\uvx.exe -ErrorAction SilentlyContinue

• step3 （可选步骤）彻底清理 uv 缓存、下载的 python 版本

执行完上面删除 exe 前执行，删掉 exe 后 uv 命令就找不到了：

uv cache clean
Remove-Item -Recurse $(uv python dir) -Force
Remove-Item -Recurse $(uv tool dir) -Force

• step4 清理 powershell 自动补全（如果之前配置过）

打开 $PROFILE，删掉里面 uv generate‑shell‑completion 的那一行，重启终端。

• step5 验证卸载成功

uv --version
# 提示不是内部命令 = 卸载完成

2.1.2 卸载uv（uv 装在 conda 虚拟环境内部）

• conda‑forge 安装的 uv

conda activate my_env
conda remove uv -y

• conda 环境内 pip install uv

conda activate my_env
pip uninstall uv -y

2.1.x 常见坑

1. 同时存在全局 uv 二进制 + conda 环境内 uv，Get‑Command uv优先命中全局的；卸载 conda 里的 uv 之后全局 uv 依然还在。
2. Remove‑Item加‑ErrorAction SilentlyContinue避免文件不存在时报错。
3. 卸载完重启终端，刷新 PATH。

2.2 安装验证

• 安装完成后，验证安装是否成功：

uv --version

输出内容类似如下，表明安装成功：

uv 0.9.15 (5eafae332 2025-12-02)

或:
uv 0.8.14 (Homebrew 2025-08-28)
...

2.3 管理 Python 版本

• uv 可以轻松管理多个 Python 版本，无需额外安装 pyenv 等工具。

查看可用的 Python 版本

uv python list

uv python list 默认输出两类内容：所有可用版本（标 <download available>，只是 "能下载"）和本机已发现的解释器。而 "已发现" 只来自这几种途径：

发现来源	说明
uv 自托管安装	UV_PYTHON_INSTALL_DIR 下（我的电脑上是 E:\ProgramData\uv-data\python\...）
PATH 中的 python	只要在 PATH 里就能被看到
激活的虚拟环境	通过 VIRTUAL_ENV 变量（uv run/uv sync 时按此顺序找）
激活的 conda 环境	通过 CONDA_PREFIX 变量，且仅在已激活时生效
Windows 已知位置	py launcher 注册表、常见安装目录（如 Program Files(x86)\Python\3.8.5、Anaconda 这类）

(base) PS C:\Users\Johnny> echo $env:UV_PYTHON_INSTALL_DIR
E:\Program-Data\uv-data\python
(base) PS C:\Users\Johnny> echo $env:VIRTUAL_ENV
(base) PS C:\Users\Johnny> echo $env:CONDA_PREFIX
D:\Program\Miniforge

关键点：uv 不会去读 conda env list 的清单，也不会扫描 envs\ 目录。

你的 python-3.12 环境没有激活、不在 PATH 里，对 uv 来说它就 "不存在"。
而上面截图中被识别出来的 3.8.5 和 Anaconda\python.exe，是因为它们位于 Windows 已知位置或 PATH 里，被当作 "操作系统 / 系统 Python" 发现了（uv 不区分 "conda 装的" 和 "系统装的"，只区分 uv 托管与非托管）。

安装特定版本的 Python

# 安装最新的 Python 3.12
uv python install 3.12

# 安装特定版本
uv python install 3.11.6

# 安装 PyPy 版本
uv python install pypy3.10

设置全局默认 Python 版本

uv python default 3.12

在项目中指定 Python 版本

# 为当前项目固定 Python 3.11
uv python pin 3.11

这会创建 .python-version 文件，标识项目所需的 Python 版本。

2.4 管理虚拟环境

• 创建并激活虚拟环境：

# 创建名为 .venv 的虚拟环境（默认）
uv venv

# 激活环境（macOS/Linux）
source .venv/bin/activate

# 激活环境（Windows）
.venv\Scripts\activate

2.5 依赖包管理

• 安装依赖包：

# 安装最新版本
uv pip install requests

# 安装特定版本
uv pip install requests==2.31.0

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

• 安装包到开发环境：

uv pip install --dev pytest

• 升级包：

uv pip upgrade requests

• 卸载包：

uv pip uninstall requests

• 导出依赖：

# 导出当前环境的依赖
uv pip freeze > requirements.txt

# 导出生产环境依赖（排除开发依赖）
uv pip freeze --production > requirements.txt

2.5 项目管理

• uv 支持 pyproject.toml 格式的项目管理，这是现代 Python 项目的标准配置文件。

• 初始化一个新项目：

uv init my_project
cd my_project

这会创建基本的项目结构和 pyproject.toml 文件。

• 安装项目的依赖：

uv sync

这个命令会根据 pyproject.toml 和 requirements.txt 安装所有依赖。类似于 pip install -e . 但更高效。

说明：

uv sync 是一个依赖管理命令，它的作用类似于您可能更熟悉的 pip install -r requirements.txt，但更快、更强大、更可靠。
您可以把它理解为："一键安装这个项目正常运行所需的所有第三方软件包（依赖库）"。
uv sync 如果安装太慢，可以设置国内镜像源 https://pypi.tuna.tsinghua.edu.cn/simple：

在项目根目录的 pyproject.toml 文件 [tool.uv] 处设置 index-url：

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

2.x 使用场景集

2.x.1 场景: pip 的平替

• 如果你只想把uv当作更快的pip，直接替换命令就行：

# 创建虚拟环境
uv venv

# 激活环境（和之前一样）
source .venv/bin/activate     # macOS/Linux
.venv\Scripts\activate        # Windows
source .venv/Scripts/activate # Windows on Git Bash


# 安装包
uv pip install pandas numpy

# 导出依赖
uv pip freeze > requirements.txt

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

• 基本上就是把pip换成uv pip，其他都一样。

• 对于已有项目，如果需要迁移的话，可以采样【渐进式迁移方式】：

• 先在本地开发环境试用uv
• 验证没问题后，更新CI/CD配置
• 团队成员逐步切换

• 另外，因为uv和pip是兼容的，【迁移过程】中几乎不会出现环境上冲突。

2.x.2 迁移到 uv

如果你正在使用其他工具，可以轻松迁移到 uv：

• 对于使用 pip + virtualenv 的项目：

# 创建并激活 uv 虚拟环境
uv venv
source .venv/bin/activate

# 安装依赖
uv pip install -r requirements.txt

• 对于使用 pip-tools 的项目：

uv pip compile requirements.in -o requirements.txt
uv pip sync

• 对于使用 poetry 或 pdm 的项目：

# 直接使用现有的 pyproject.toml
uv sync

3 项目实践

CASE 从 0 到 1 用 uv 管理一个 Python 项目，按生命周期分阶段整理的常用命令 (必读)

1. 安装与升级 uv

场合	命令	说明
uv 的安装	略（参见上述章节）
升级 uv 自身	uv self update	更新到最新版
查看版本	uv --version	确认安装结果

2. 项目初始化

场合	命令	说明
创建默认项目	uv init my-project	生成 pyproject.toml、main.py、.python-version、.gitignore
创建应用型项目	uv init --app my-project	默认形态，入口为 main.py
创建库项目	uv init --lib my-project	src 布局（src/ 下放包），适合要发布的库
初始化为可发布包	uv init --package my-project	等价于 --lib 的旧叫法
指定项目名	uv init --name demo	目录名与包名不一致时用
在已有目录初始化	uv init	直接在当前目录生成骨架（但如果已存在pyproject.toml文件时将报错）

• 推荐的项目目录骨架:

• 推荐项目结构 - Python 编码规范 - 博客园/千千寰宇

3. Python 版本管理

场合	命令	说明
安装指定版本解释器	uv python install 3.12	自动下载管理独立于系统的 Python
安装多个版本	uv python install 3.11 3.12 3.13	一次装多个
卸载指定版本解释器	uv python uninstall 3.12	卸载独立于系统的 Python
列出可安装版本	uv python list	含已安装与可下载
固定项目版本	uv python pin 3.12	写入 .python-version，项目锁定该版本
查找解释器路径	uv python find	输出当前解析到的 Python 路径

4. 项目的虚拟环境

场合	命令	说明
创建虚拟环境	uv venv	默认在项目下生成 .venv
指定版本创建	uv venv --python 3.12	基于指定解释器创建
激活环境（Windows）	.venv\Scripts\activate	手动激活后直接用 python
激活环境（macOS/Linux）	source .venv/bin/activate	同上
删除重建环境	rm -rf .venv 后重新 uv sync	uv 环境下环境可随时重建

5. 依赖管理（核心）

场合	命令	说明
添加运行时依赖	uv add requests	自动解析、写 pyproject.toml 并生成锁文件
带版本约束添加	uv add "requests>=2.31,<3"	支持版本区间语法
添加开发依赖	uv add --dev pytest	写入 pyproject.toml 的 [dependency-groups].dev
添加可选依赖组	uv add --group docs sphinx	自定义分组，运行时用 --extra docs
移除依赖	uv remove requests	从 pyproject 与锁文件一并移除
同步环境	uv sync	按锁文件安装/更新全部依赖到 .venv
重新生成锁文件	uv lock	无锁文件时创建，或刷新
升级依赖版本	uv lock --upgrade	升级锁文件中所有依赖
只升级某个包	uv lock --upgrade-package requests	定向升级
查看依赖树	uv tree	展示依赖层级关系
导出 requirements.txt	uv export --format requirements-txt -o requirements.txt	给 CI 或老工具使用

6. 日常运行与开发

场合	命令	说明
运行脚本	uv run python main.py	自动保证环境已同步
运行测试	uv run pytest	直接在项目环境跑 pytest
启动服务	uv run uvicorn app:app --reload	例：FastAPI 服务
带临时依赖运行	uv run --with jupyter jupyter lab	依赖不写入项目，用完即弃
运行时不同步	uv run --no-sync python main.py	跳过自动 sync，加快启动
打开交互式解释器	uv run python	进入项目环境 REPL

7. 打包与发布

场合	命令	说明
构建分发包	uv build	生成 sdist 和 wheel 到 dist/
只构建源码包	uv build --sdist	—
只构建 wheel	uv build --wheel	—
发布到 PyPI	uv publish	需要已配置凭证（token/~/.pypirc）
发布前校验	uv publish --dry-run	不实际上传，先试跑

8. 全局工具（uvx / uv tool）

场合	命令	说明
临时运行工具	uvx ruff check .	下载即用，不污染项目环境，等价于 uv tool run
安装全局工具	uv tool install ruff	常驻安装，供所有项目使用
列出已装工具	uv tool list	—
卸载全局工具	uv tool uninstall ruff	—
升级全局工具	uv tool upgrade ruff	—

9. 缓存与维护

场合	命令	说明
查看缓存目录	uv cache dir	输出缓存位置
清理全部缓存	uv cache clean	释放磁盘空间
清理过期缓存	uv cache prune	只删不再需要的缓存条目，更安全

X. 使用要点

• 核心循环是 uv add → uv run：uv run 会自动按【锁文件】同步环境再【执行命令】，日常几乎不需要手动 uv venv + activate。
• 锁文件（uv.lock） 是跨机器/CI 保持一致的关键，应提交到 git；升级依赖用 uv lock --upgrade 而不是直接改 pyproject。
• uvx 与 uv add --dev 搭配使用，能让项目环境保持干净：一次性工具用 uvx，开发期工具进 dev 组。
• 想了解某条命令的完整参数，随时可以用 uv <子命令> --help 查看。

Z FAQ for uv

Q: python 的 uv 安装的python包默认是在哪个路径？能否将该C盘的路径修改为别的磁盘盘符？（避免Windows的C盘存储空间膨胀、必读）

• uv 在 Windows 上并不是“所有包装到同一个目录”，它分缓存（本地磁盘占用的大头）、Python 解释器、全局工具、项目虚拟环境、系统包几块，各自默认位置和改法不一样。

想救 C 盘，主要改前三类，项目环境本来就可以放任意盘。

uv 在 Windows 上并不是“所有包装到同一个目录”，它分缓存、Python 解释器、全局工具、项目虚拟环境、系统包几块，各自默认位置和改法不一样。想救 C 盘，主要改前三类，项目环境本来就可以放任意盘。

默认路径（Windows）

• 依赖缓存（wheels、构建产物）：默认在%LOCALAPPDATA%\uv\cache

也就是 C:\Users\你\AppData\Local\uv\cache

• uv 自己下载管理的 Python 解释器：

默认在 uv 的“Python 安装目录”，可用 uv python dir 查；
旧版/部分资料在 %LOCALAPPDATA%\uv\python 或用户目录 .uv\python，以你本机命令输出为准

• 全局工具（uv tool install 装的 ruff、black 等）：工具环境目录 + 可执行目录，可用 uv tool dir 查；

配置可用 UV_TOOL_DIR、可执行 bin 可用相关 bin 变量

• 配置/持久数据：%APPDATA%\uv（roaming）、%APPDATA%\uv\data 一类

• 临时文件：走 %TMP% / %TEMP%

• 项目虚拟环境：uv venv 默认建在当前目录 .venv；uv sync 按项目来，不强制 C 盘

• 系统全局包（慎用 uv pip install --system）：装进你那个系统 Python 的 site-packages，路径完全由 Python 安装位置决定（比如 C:\Users\你\AppData\Local\Programs\Python\Python312\Lib\site-packages 或虚拟环境内）

• 快速看自己机器实际值：

uv cache dir
uv python dir
uv tool dir

改到其他盘（推荐变量）

• 系统环境变量里加这几个，重启终端生效。以 D 盘为例：

• UV_CACHE_DIR → D:\uv\cache（最该改，缓存最大）
• UV_PYTHON_INSTALL_DIR → D:\uv\python（uv 下载的各版本解释器）
• UV_TOOL_DIR → D:\uv\tools（全局工具环境）
• 可执行 bin 目录（让 uvx/工具命令可找到）按需设 bin 变量，例如指向 D:\uv\bin 并把这个目录加入 PATH
• UV_DATA_DIR → D:\uv\data（持久数据）、UV_CONFIG_FILE → D:\uv\uv.toml（如果想把配置也挪走）
• 临时目录若也想挪：TMP/TEMP 改 D:\tmp（影响所有程序，谨慎）

• PowerShell 永久写用户变量：

[Environment]::SetEnvironmentVariable("UV_CACHE_DIR", "D:\uv\cache", "User")
[Environment]::SetEnvironmentVariable("UV_PYTHON_INSTALL_DIR", "D:\uv\python", "User")
[Environment]::SetEnvironmentVariable("UV_TOOL_DIR", "D:\uv\tools", "User")
[Environment]::SetEnvironmentVariable("UV_DATA_DIR", "D:\uv\data", "User")

图形界面：此电脑→属性→高级→环境变量→用户变量→新建上述变量→确定→重开 PowerShell/CMD。

• 验证：

uv cache dir
uv python dir
uv tool dir
uv venv --python 3.12   :: 看解释器是否落到 D:\uv\python

虚拟环境 / 项目依赖怎么不占 C 盘

• 每个项目用 venv，直接把项目文件夹建在 D 盘即可，uv venv 会在项目内生成 .venv，天然不在 C 盘。
• 想所有项目共用一个中心化 venv 目录：用 UV_PROJECT_ENVIRONMENT 指定绝对路径，或在 uv.toml 里配置 project environment；但注意多个项目共用一个 venv 容易依赖互相污染，一般不建议。
• CI/临时不想写缓存：uv ... --no-cache 或 UV_NO_CACHE=1。

如果你说的是“pip 那种装到系统 Python”

• 别用 uv pip install --system，它会装进系统 Python 的 site-packages；要省 C 盘就把系统 Python 本身装到 D 盘（安装器自定义路径）

或干脆不用 --system，全部走项目 .venv。

• 用 uv python install 3.12 让 uv 托管解释器，并把 UV_PYTHON_INSTALL_DIR 指 D 盘，之后 uv venv --python 3.12、uv run 都不会回退到 C 盘系统 Python。

顺手清理

uv cache clean        :: 全清缓存
uv cache clean 包名   :: 只清某个包

缓存清了能回收不少空间；解释器目录和工具目录按版本累积，不定期手动删旧版本即可。

实操记录(必读)

• 查看操作

:: 查看目录
uv cache dir
  例如: C:\Users\Johnny\AppData\Local\uv\cache
uv python dir
  例如: C:\Users\Johnny\AppData\Roaming\uv\python
uv tool dir
  例如: C:\Users\Johnny\AppData\Roaming\uv\tools


:: 查看目录对应的存储空间占用情况 | cache 占用了几个GB，其他目录几十 MB（可忽略）
(Get-ChildItem (uv cache dir) -File -Recurse | Measure-Object -Property Length -Sum).Sum/1MB
(Get-ChildItem (uv python dir) -File -Recurse | Measure-Object -Property Length -Sum).Sum/1MB
(Get-ChildItem (uv tool dir) -File -Recurse | Measure-Object -Property Length -Sum).Sum/1MB

• 清理操作

:: 全清缓存
uv cache clean

:: 查验占用的空间大小
(Get-ChildItem (uv cache dir) -File -Recurse | Measure-Object -Property Length -Sum).Sum/1MB

此时的存储空间占用：必为 0

• 修改操作

• 配置环境变量:

UV_CACHE_DIR = E:\Program-Data\uv-data\cache
UV_PYTHON_INSTALL_DIR = E:\Program-Data\uv-data\python
UV_TOOL_DIR = E:\Program-Data\uv-data\tools

• 二次查验（新开powershell窗口）

:: 查看路径是否及时更新了
uv cache dir
uv python dir
uv tool dir

:: 查看uv可用的 python 版本环境
uv python list

:: 安装1个新环境，并查看其存放路径是否已在新环境的路径中
uv python install 3.13
uv python list

Y 推荐文献

• UV

• docs : https://docs.astral.sh/uv/
• github : https://github.com/astral-sh/uv

• [Python3] Python 基础教程 - 博客园/千千寰宇

• [Python] 包管理器Pip - 博客园/千千寰宇

• [Python] Miniforge: 开源版conda环境管理器 - 博客园/千千寰宇

• [Python/虚拟环境/包管理] conda：多环境管理与包管理器 - 博客园/千千寰宇

• [Python] Python 虚拟环境管理 - 博客园/千千寰宇

X 参考文献

• 2025年，Python包管理工具已经由pip变成了uv？ - Weixin/机器学习实验室 2025.11.13