5.4 存储

原文链接: https://docs.astral.sh/uv/reference/storage/

5.4 存储

存储目录

uv 使用以下高层目录进行存储。

对于每个位置，uv 会按给定顺序检查环境变量是否存在，并使用找到的第一个路径。

存储目录的路径与平台相关。uv 在 Linux 和 macOS 上遵循 XDG 约定，在 Windows 上遵循 Known Folder 方案。

临时目录

临时目录用于存放短暂数据。

• Unix
• Windows

缓存目录

缓存目录用于存放可丢弃、但长期保留会有用的数据。

• Unix
• Windows

持久数据目录

持久数据目录用于存放不可丢弃的数据。

• Unix
• Windows

配置目录

配置目录用于存放对 uv 设置的修改。

用户级配置

• Unix
• Windows

系统级配置

• Unix
• Windows

可执行文件目录

可执行文件目录用于存放用户可以运行的文件，即一个应当位于 PATH 上的目录。

• Unix
• Windows

数据类型

依赖缓存

uv 使用本地缓存以避免重复下载和重复构建依赖。

默认情况下缓存存放在缓存目录中，但可以通过命令行参数、环境变量或设置覆盖，细节见缓存文档。缓存被禁用时，缓存会存放在临时目录中。

使用 uv cache dir 显示当前的缓存目录路径。

重要

为获得最佳性能，缓存目录需要与虚拟环境位于同一文件系统上。

Python 版本

uv 可以安装受管的 Python 版本，例如通过 uv python install。

默认情况下，uv 管理的 Python 版本存放在持久数据目录的 python/ 子目录中，例如 ~/.local/share/uv/python。

使用 uv python dir 显示 Python 安装目录。

使用 UV_PYTHON_INSTALL_DIR 环境变量覆盖安装目录。

注意

改变 Python 的安装位置不会自动反映到既有虚拟环境；它们会继续指向旧位置，需要手动更新（例如重新创建它们）。

Python 可执行文件

uv 会为 Python 版本安装可执行文件，例如 python3.13。

默认情况下，Python 可执行文件存放在可执行文件目录中。

使用 uv python dir --bin 显示 Python 可执行文件目录。

使用 UV_PYTHON_BIN_DIR 环境变量覆盖 Python 可执行文件目录。

工具

uv 可以通过 uv tool install 把 Python 包安装为命令行工具。

默认情况下，工具安装在持久数据目录的 tools/ 子目录中，例如 ~/.local/share/uv/tools。

使用 uv tool dir 显示工具安装目录。

使用 UV_TOOL_DIR 环境变量配置安装目录。

工具可执行文件

uv 会为已安装的工具安装可执行文件，例如 ruff。

默认情况下，工具可执行文件存放在可执行文件目录中。

使用 uv tool dir --bin 显示工具可执行文件目录。

使用 UV_TOOL_BIN_DIR 环境变量配置工具可执行文件目录。

uv 可执行文件

使用 uv 的独立安装器安装 uv 时，uv 和 uvx 可执行文件会被安装到可执行文件目录。

使用 UV_INSTALL_DIR 环境变量配置 uv 的安装目录。

配置文件

uv 的行为可以通过 TOML 文件配置。

配置文件会在配置目录中发现。

更多细节请参阅配置文件文档。

项目虚拟环境

处理项目时，uv 会为每个项目创建专用虚拟环境。

默认情况下，项目虚拟环境创建在项目或工作区根目录的 .venv 中，即 pyproject.toml 旁边。

使用 UV_PROJECT_ENVIRONMENT 环境变量覆盖该位置。更多细节请参阅项目环境文档。

借助 centralized-project-envs 预览特性，uv 会把默认项目环境存放在缓存目录中。它们可以通过 uv cache clean 或 uv cache prune 移除，并在下次需要时重建。细节请参阅集中式项目环境文档。

脚本虚拟环境

运行带内联元数据的脚本时，uv 会为每个脚本在缓存目录中创建专用虚拟环境。