尧图网页设计 
uv 独立安装器配置详解自定义安装路径、禁用 Shell 修改与无管理安装【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv本文基于 uv 官方参考文档 installer.md系统讲解 uv 独立安装器standalone installer的四个核心能力使用UV_INSTALL_DIR更改安装路径、使用UV_NO_MODIFY_PATH禁用 shell 配置文件修改、使用UV_UNMANAGED_INSTALL在 CI 等临时环境中执行无管理安装以及直接向安装脚本传参。结合仓库源码还会剖析这些环境变量为何能在uv self update中持续生效以及“安装回执”receipt机制的底层原理。uv 独立安装器概述uv 提供独立的安装脚本可在 macOS、Linux 与 Windows 上一键安装具体方式见 安装指南$ curl -LsSf https://astral.sh/uv/install.sh | shPS powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex安装脚本安装后uv与uvx可执行文件会进入 uv 的“可执行文件目录”executable directory并可能更新 shell 配置文件以保证该目录在PATH中。存储参考文档 对该目录的解析顺序Unix 平台定义为$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/binWindows 平台则依次尝试%XDG_BIN_HOME%、%XDG_DATA_HOME%\..\bin、%USERPROFILE%\.local\bin。这也是为什么 安装指南 中的卸载步骤是删除~/.local/bin/uv和~/.local/bin/uvx。使用UV_INSTALL_DIR更改安装路径默认情况下uv 安装在用户级可执行文件目录中。若要更改安装路径在调用安装脚本前设置环境变量UV_INSTALL_DIR即可。macOS 与 Linux$ curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR/custom/path shWindowsPS powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR C:\Custom\Path;irm https://astral.sh/uv/install.ps1 | iex}从源码定义看env_vars.rs/// The directory in which to install uv using the standalone installer and self update feature. /// Defaults to ~/.local/bin. #[attr_added_in(0.5.0)] pub const UV_INSTALL_DIR: static str UV_INSTALL_DIR;两个要点值得注意仅影响二进制位置不影响数据存储更改安装路径只决定uv/uvx可执行文件落在哪里缓存、Python 解释器、工具等数据仍然存放在存储参考文档所述的默认位置如缓存目录~/.cache/uv、数据目录~/.local/share/uv。若要自定义这些位置需使用各自对应的环境变量如UV_PYTHON_INSTALL_DIR、UV_TOOL_DIR。对uv self update同样生效从注释看UV_INSTALL_DIR同时作用于安装器与自更新功能即自更新下载的新版本也会写回该目录。使用UV_NO_MODIFY_PATH禁用 Shell 修改安装器可能会更新你的 shell 配置文件如~/.zshrc、~/.bashrc把可执行文件目录写入PATH。若不希望它改动 shell 配置可设置UV_NO_MODIFY_PATH$ curl -LsSf https://astral.sh/uv/install.sh | env UV_NO_MODIFY_PATH1 sh其源码定义env_vars.rs说明它还兼容旧变量名INSTALLER_NO_MODIFY_PATH/// Avoid modifying the PATH environment variable when installing uv using the standalone /// installer and self update feature. INSTALLER_NO_MODIFY_PATH is also supported as an /// alias, for backwards compatibility. #[attr_added_in(0.8.4)] pub const UV_NO_MODIFY_PATH: static str UV_NO_MODIFY_PATH;这一设置的持续性有源码级依据uv self update会重新执行安装脚本因此可能再次修改 shell 配置。uv 在首次安装时把“是否修改 PATH”的决定写入安装回执receipt后续自更新时再读取该回执。在 self_update.rs 中可以看到这一逻辑// If we cant determine the previous PATH behavior, abort rather than potentially changing the // users shell configuration unexpectedly. let modify_path load_receipt_modify_path(uv) .context(Failed to determine whether the existing standalone install modified PATH)?;即如果无法确定初次安装时是否修改了 PATHuv 会主动中止自更新而不是冒着意外改动用户 shell 配置的风险继续。对应的 load_receipt_modify_path 从回执 JSON 中解析modify_path字段且“旧回执缺失该字段时默认视为true”单元测试 test_standalone_install_receipt_defaults_modify_path_to_true 验证了这一点。因此用UV_NO_MODIFY_PATH安装的 uv后续执行uv self update也不会再修改 shell 配置文件——这与 安装指南 中“更新 uv 会重新运行安装器并可能修改 shell 配置可用UV_NO_MODIFY_PATH1禁用”的说明一致。使用UV_UNMANAGED_INSTALL进行无管理安装在 CI 等临时ephemeral环境中通常不希望安装器触碰 shell 配置文件或环境变量。此时可用UV_UNMANAGED_INSTALL把 uv 安装到指定路径同时阻止安装器做任何 shell 层面的修改$ curl -LsSf https://astral.sh/uv/install.sh | env UV_UNMANAGED_INSTALL/custom/path sh源码定义env_vars.rs/// Used ephemeral environments like CI to install uv to a specific path while preventing /// the installer from modifying shell profiles or environment variables. #[attr_added_in(0.5.0)] pub const UV_UNMANAGED_INSTALL: static str UV_UNMANAGED_INSTALL;使用UV_UNMANAGED_INSTALL安装后自更新能力会被关闭。原因在于uv self update的整个流程建立在“安装回执”之上self_update 首先执行updater.load_receipt()找不到回执就认定“uv 很可能不是通过独立安装器安装的”并报错退出// Load the install receipt for the current binary. If the receipt is not found, then // uv was likely installed via a package manager. let Ok(updater) updater.load_receipt() else { ... Self-update is only available for uv binaries installed via the standalone installation scripts. };无管理安装属于“非管理”形态不生成可供自更新使用的回执因此uv self update不可用——这与 CI 场景的诉求正好契合容器每次都是全新构建直接用安装脚本或制品管理器锁定版本即可无需二进制自我升级。直接向安装脚本传参文档推荐使用环境变量传参因为它们在多平台间语义一致但选项也可以直接传给安装脚本本身。例如查看可用选项$ curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --help注意sh -s -- --help中的--其作用是把--help从 shell 参数分隔开作为脚本自身的参数传入。Windows 侧的install.ps1同理支持直接传参。安装器相关的其他环境变量围绕安装器与自更新env_vars.rs 中还定义了若干配套变量在受限网络或镜像场景下有用环境变量作用引入版本UV_INSTALL_DIR安装目录默认~/.local/bin同时作用于安装器与uv self update0.5.0UV_UNMANAGED_INSTALL安装到指定路径且不修改 shell 配置同时禁用自更新0.5.0UV_NO_MODIFY_PATH避免安装/自更新时修改PATH兼容旧别名INSTALLER_NO_MODIFY_PATH0.8.4UV_DOWNLOAD_URL覆盖独立安装器的下载 URL兼容旧别名INSTALLER_DOWNLOAD_URL0.8.4UV_INSTALLER_GITHUB_BASE_URL覆盖自更新/安装器的 GitHub Releases 下载基址0.5.0UV_INSTALLER_GHE_BASE_URL覆盖 GitHub Enterprise 下载基址0.5.0其中 UV_INSTALLER_GITHUB_BASE_URL 的注释说明对于uv self update这两个更具体的安装源变量优先于通用的 Astral 镜像变量。在自更新实现中is_official_public_uv_install 也会检查这两个变量是否被设置以决定走“官方公开安装”路径还是“自定义源”路径。自更新与安装回执机制小结把本文涉及的机制串联起来独立安装器安装 uv脚本下载对应平台的二进制写入安装目录默认可执行文件目录可用UV_INSTALL_DIR覆盖并生成记录安装来源与路径行为的安装回执。uv self update复用同一套安装器self_update 先加载并校验回执check_receipt_is_for_this_executable 能检测出“存在多份 uv、当前二进制并非安装器所装”的冲突再按原安装参数含是否修改 PATH重跑安装脚本。非独立安装器安装的 uv 无法自更新通过 pip、brew 等包管理器安装的 uv 没有回执uv self update会明确报错并提示改用包管理器升级——这也是安装指南建议此类用户执行pip install --upgrade uv的原因。无管理安装主动放弃自更新UV_UNMANAGED_INSTALL面向 CI 等临时环境不产生管理回执uv self update随之不可用。总结场景环境变量效果自定义二进制安装位置UV_INSTALL_DIR/custom/pathuv/uvx安装到指定目录数据目录不变不改动 shell 配置UV_NO_MODIFY_PATH1安装与自更新均不修改PATH相关配置文件CI / 临时环境UV_UNMANAGED_INSTALL/custom/path装到指定路径、不碰 shell 配置且禁用自更新查看脚本可用选项sh -s -- --help直接给安装脚本传参跨平台时推荐环境变量配置细节可对照 installer 参考文档、storage 参考文档 与 安装指南环境变量定义见 crates/uv-static/src/env_vars.rs自更新实现见 crates/uv/src/commands/self_update.rs。【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 uv 独立安装器配置详解：自定义安装路径、禁用 Shell 修改与无管理安装
uv 独立安装器配置详解自定义安装路径、禁用 Shell 修改与无管理安装【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv本文基于 uv 官方参考文档 installer.md系统讲解 uv 独立安装器standalone installer的四个核心能力使用UV_INSTALL_DIR更改安装路径、使用UV_NO_MODIFY_PATH禁用 shell 配置文件修改、使用UV_UNMANAGED_INSTALL在 CI 等临时环境中执行无管理安装以及直接向安装脚本传参。结合仓库源码还会剖析这些环境变量为何能在uv self update中持续生效以及“安装回执”receipt机制的底层原理。uv 独立安装器概述uv 提供独立的安装脚本可在 macOS、Linux 与 Windows 上一键安装具体方式见 安装指南$ curl -LsSf https://astral.sh/uv/install.sh | shPS powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex安装脚本安装后uv与uvx可执行文件会进入 uv 的“可执行文件目录”executable directory并可能更新 shell 配置文件以保证该目录在PATH中。存储参考文档 对该目录的解析顺序Unix 平台定义为$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/binWindows 平台则依次尝试%XDG_BIN_HOME%、%XDG_DATA_HOME%\..\bin、%USERPROFILE%\.local\bin。这也是为什么 安装指南 中的卸载步骤是删除~/.local/bin/uv和~/.local/bin/uvx。使用UV_INSTALL_DIR更改安装路径默认情况下uv 安装在用户级可执行文件目录中。若要更改安装路径在调用安装脚本前设置环境变量UV_INSTALL_DIR即可。macOS 与 Linux$ curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR/custom/path shWindowsPS powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR C:\Custom\Path;irm https://astral.sh/uv/install.ps1 | iex}从源码定义看env_vars.rs/// The directory in which to install uv using the standalone installer and self update feature. /// Defaults to ~/.local/bin. #[attr_added_in(0.5.0)] pub const UV_INSTALL_DIR: static str UV_INSTALL_DIR;两个要点值得注意仅影响二进制位置不影响数据存储更改安装路径只决定uv/uvx可执行文件落在哪里缓存、Python 解释器、工具等数据仍然存放在存储参考文档所述的默认位置如缓存目录~/.cache/uv、数据目录~/.local/share/uv。若要自定义这些位置需使用各自对应的环境变量如UV_PYTHON_INSTALL_DIR、UV_TOOL_DIR。对uv self update同样生效从注释看UV_INSTALL_DIR同时作用于安装器与自更新功能即自更新下载的新版本也会写回该目录。使用UV_NO_MODIFY_PATH禁用 Shell 修改安装器可能会更新你的 shell 配置文件如~/.zshrc、~/.bashrc把可执行文件目录写入PATH。若不希望它改动 shell 配置可设置UV_NO_MODIFY_PATH$ curl -LsSf https://astral.sh/uv/install.sh | env UV_NO_MODIFY_PATH1 sh其源码定义env_vars.rs说明它还兼容旧变量名INSTALLER_NO_MODIFY_PATH/// Avoid modifying the PATH environment variable when installing uv using the standalone /// installer and self update feature. INSTALLER_NO_MODIFY_PATH is also supported as an /// alias, for backwards compatibility. #[attr_added_in(0.8.4)] pub const UV_NO_MODIFY_PATH: static str UV_NO_MODIFY_PATH;这一设置的持续性有源码级依据uv self update会重新执行安装脚本因此可能再次修改 shell 配置。uv 在首次安装时把“是否修改 PATH”的决定写入安装回执receipt后续自更新时再读取该回执。在 self_update.rs 中可以看到这一逻辑// If we cant determine the previous PATH behavior, abort rather than potentially changing the // users shell configuration unexpectedly. let modify_path load_receipt_modify_path(uv) .context(Failed to determine whether the existing standalone install modified PATH)?;即如果无法确定初次安装时是否修改了 PATHuv 会主动中止自更新而不是冒着意外改动用户 shell 配置的风险继续。对应的 load_receipt_modify_path 从回执 JSON 中解析modify_path字段且“旧回执缺失该字段时默认视为true”单元测试 test_standalone_install_receipt_defaults_modify_path_to_true 验证了这一点。因此用UV_NO_MODIFY_PATH安装的 uv后续执行uv self update也不会再修改 shell 配置文件——这与 安装指南 中“更新 uv 会重新运行安装器并可能修改 shell 配置可用UV_NO_MODIFY_PATH1禁用”的说明一致。使用UV_UNMANAGED_INSTALL进行无管理安装在 CI 等临时ephemeral环境中通常不希望安装器触碰 shell 配置文件或环境变量。此时可用UV_UNMANAGED_INSTALL把 uv 安装到指定路径同时阻止安装器做任何 shell 层面的修改$ curl -LsSf https://astral.sh/uv/install.sh | env UV_UNMANAGED_INSTALL/custom/path sh源码定义env_vars.rs/// Used ephemeral environments like CI to install uv to a specific path while preventing /// the installer from modifying shell profiles or environment variables. #[attr_added_in(0.5.0)] pub const UV_UNMANAGED_INSTALL: static str UV_UNMANAGED_INSTALL;使用UV_UNMANAGED_INSTALL安装后自更新能力会被关闭。原因在于uv self update的整个流程建立在“安装回执”之上self_update 首先执行updater.load_receipt()找不到回执就认定“uv 很可能不是通过独立安装器安装的”并报错退出// Load the install receipt for the current binary. If the receipt is not found, then // uv was likely installed via a package manager. let Ok(updater) updater.load_receipt() else { ... Self-update is only available for uv binaries installed via the standalone installation scripts. };无管理安装属于“非管理”形态不生成可供自更新使用的回执因此uv self update不可用——这与 CI 场景的诉求正好契合容器每次都是全新构建直接用安装脚本或制品管理器锁定版本即可无需二进制自我升级。直接向安装脚本传参文档推荐使用环境变量传参因为它们在多平台间语义一致但选项也可以直接传给安装脚本本身。例如查看可用选项$ curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --help注意sh -s -- --help中的--其作用是把--help从 shell 参数分隔开作为脚本自身的参数传入。Windows 侧的install.ps1同理支持直接传参。安装器相关的其他环境变量围绕安装器与自更新env_vars.rs 中还定义了若干配套变量在受限网络或镜像场景下有用环境变量作用引入版本UV_INSTALL_DIR安装目录默认~/.local/bin同时作用于安装器与uv self update0.5.0UV_UNMANAGED_INSTALL安装到指定路径且不修改 shell 配置同时禁用自更新0.5.0UV_NO_MODIFY_PATH避免安装/自更新时修改PATH兼容旧别名INSTALLER_NO_MODIFY_PATH0.8.4UV_DOWNLOAD_URL覆盖独立安装器的下载 URL兼容旧别名INSTALLER_DOWNLOAD_URL0.8.4UV_INSTALLER_GITHUB_BASE_URL覆盖自更新/安装器的 GitHub Releases 下载基址0.5.0UV_INSTALLER_GHE_BASE_URL覆盖 GitHub Enterprise 下载基址0.5.0其中 UV_INSTALLER_GITHUB_BASE_URL 的注释说明对于uv self update这两个更具体的安装源变量优先于通用的 Astral 镜像变量。在自更新实现中is_official_public_uv_install 也会检查这两个变量是否被设置以决定走“官方公开安装”路径还是“自定义源”路径。自更新与安装回执机制小结把本文涉及的机制串联起来独立安装器安装 uv脚本下载对应平台的二进制写入安装目录默认可执行文件目录可用UV_INSTALL_DIR覆盖并生成记录安装来源与路径行为的安装回执。uv self update复用同一套安装器self_update 先加载并校验回执check_receipt_is_for_this_executable 能检测出“存在多份 uv、当前二进制并非安装器所装”的冲突再按原安装参数含是否修改 PATH重跑安装脚本。非独立安装器安装的 uv 无法自更新通过 pip、brew 等包管理器安装的 uv 没有回执uv self update会明确报错并提示改用包管理器升级——这也是安装指南建议此类用户执行pip install --upgrade uv的原因。无管理安装主动放弃自更新UV_UNMANAGED_INSTALL面向 CI 等临时环境不产生管理回执uv self update随之不可用。总结场景环境变量效果自定义二进制安装位置UV_INSTALL_DIR/custom/pathuv/uvx安装到指定目录数据目录不变不改动 shell 配置UV_NO_MODIFY_PATH1安装与自更新均不修改PATH相关配置文件CI / 临时环境UV_UNMANAGED_INSTALL/custom/path装到指定路径、不碰 shell 配置且禁用自更新查看脚本可用选项sh -s -- --help直接给安装脚本传参跨平台时推荐环境变量配置细节可对照 installer 参考文档、storage 参考文档 与 安装指南环境变量定义见 crates/uv-static/src/env_vars.rs自更新实现见 crates/uv/src/commands/self_update.rs。【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考