跳转至

存储

存储目录

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

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

存储目录的路径因平台而异。uv 在 Linux 和 macOS 上遵循 XDG 规范，在 Windows 上遵循 Known Folder 方案。

临时目录

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

  1. $TMPDIR
  2. /tmp
  1. %TMP%
  2. %TEMP%
  3. %USERPROFILE%

缓存目录

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

  1. $XDG_CACHE_HOME/uv
  2. $HOME/.cache/uv
  1. %LOCALAPPDATA%\uv\cache
  2. FOLDERID_LocalAppData 内的 uv\cache

持久数据目录

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

  1. $XDG_DATA_HOME/uv
  2. $HOME/.local/share/uv
  3. $CWD/.uv
  1. %APPDATA%\uv\data
  2. .\.uv

配置目录

配置目录用于存储对 uv 设置的更改。

用户级配置

  1. $XDG_CONFIG_HOME/uv
  2. $HOME/.config/uv
  1. %APPDATA%\uv
  2. FOLDERID_RoamingAppData 内的 uv

系统级配置

  1. $XDG_CONFIG_DIRS/uv
  2. /etc/uv
  1. %PROGRAMDATA%\uv
  2. FOLDERID_AppDataProgramData 内的 uv

可执行文件目录

可执行文件目录用于存放用户可运行的文件，即应在 PATH 中的目录。

  1. $XDG_BIN_HOME
  2. $XDG_DATA_HOME/../bin
  3. $HOME/.local/bin
  1. %XDG_BIN_HOME%
  2. %XDG_DATA_HOME%\..\bin
  3. %USERPROFILE%\.local\bin

数据类型

依赖缓存

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

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

使用 uv cache dir 查看当前缓存目录路径。

Important

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

Python 版本

uv 可以安装托管的 Python 版本，例如使用 uv python install。

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

使用 uv python dir 查看 Python 安装目录。

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

Note

更改 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 环境变量覆盖此位置。更多详情请参阅 项目环境文档。

脚本虚拟环境

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