Windows 11 安装 uv：手动下载、配置国内源

发布于: 2025-11-30 | 浏览量: 加载中...

返回开源软件分享列表
uv Python Windows 11 包管理器 清华源 环境变量 手动安装 PyPI 开发工具 国内镜像

Windows 11 安装 uv：手动下载、配置国内源

[TOC]

封面.png

重要声明：

uv 的安装有很多种方式，您完全可以选择任何自己喜欢的方式进行安装，并不一定非得按照本教程进行安装。

您可以先尝试执行下面两条命令自动安装，如果失败，再按照本文手动安装

> # 安装 uv（这条命令会从uv官网获取安装脚本，再从GitHub获取uv可执行文件，将uv安装到 D:\soft\uv ，最后配置Path，创建收据文件）
> powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "D:\soft\uv";irm https://astral.sh/uv/install.ps1 | iex}
> # 配置国内源
> [Environment]::SetEnvironmentVariable("UV_DEFAULT_INDEX", "https://pypi.tuna.tsinghua.edu.cn/simple/", "User")
> ```
> 
> **如果上述两条命令执行成功了，就不必再往下看了**。

## 0. 下载 uv

这里提供了国内的下载链接：[https://hanshuixin.org/go/222M](https://hanshuixin.org/go/222M)

其中包含：

```text
Windows 11 安装 uv：手动下载、配置国内源.zip
└── Windows 11 安装 uv：手动下载、配置国内源
    ├── LICENSE-APACHE
    ├── LICENSE-MIT
    ├── Windows 11 安装 uv：手动下载、配置国内源.pdf
    └── uv-x86_64-pc-windows-msvc.zip

下载Windows 11 安装 uv：手动下载、配置国内源.zip，右击，选择“全部解压缩”，解压到当前文件夹下

进入Windows 11 安装 uv：手动下载、配置国内源文件夹，找到uv-x86_64-pc-windows-msvc.zip

1. 安装、配置 uv

  1. 右击整合包中的的压缩文件 uv-x86_64-pc-windows-msvc.zip，选择“全部解压缩”，输入目标路径 D:\soft\uv，点击“提取”。

解压.png

  1. 按 Win + R 键，输入 SystemPropertiesAdvanced，敲回车，将打开“高级系统设置”。

或者，你也可以通过 点击桌面下方开始按钮 -> 设置 -> 系统 -> 系统信息 -> 高级系统设置，最终与 SystemPropertiesAdvanced 效果一致。

winR.png

  1. 在弹出的“系统属性”窗口中，点击“环境变量”。

环境变量.png

  1. 在“……的用户变量(U)”中找到 Path 变量，点击“编辑”。

Path.png

  1. 点击“新建”，输入 D:\soft\uv，选中、点击“上移”将其移至列表顶部（确保优先使用），然后点击“确定”。

uv_Path.png

  1. 配置国内源，方法如下：

    • 在“……的用户变量(U)”下，点击“新建”
    • 变量名填：UV_DEFAULT_INDEX
    • 变量值填：https://pypi.tuna.tsinghua.edu.cn/simple/
    • 点击“确定”

国内源.png

  1. 依次点击“环境变量”和“系统属性”窗口的“确定”保存设置。

最后确定.png

  1. 创建收据文件（用于未来更新），方法如下：

    • 按 Win + R 键，输入 %LOCALAPPDATA%，按回车，会打开当前用户的本地应用程序数据文件夹

    • 新建一个文件夹命名为 uv 收据目录.png

    • 进入新建的 uv 文件夹

    • 创建一个文本文件，名为 uv-receipt.json，注意将 .txt 改为 .json

    • 输入以下内容，保存并关闭文件：

     {"binaries":["uv.exe","uvx.exe","uvw.exe"],"binary_aliases":{},"cdylibs":[],"cstaticlibs":[],
 "install_layout":"flat","install_prefix":"D:\\soft\\uv","modify_path":true,"provider":{"source":"cargo-dist",
 "version":"0.28.7"},"source":{"app_name":"uv","name":"uv","owner":"astral-sh","release_type":"github"},
 "version":"0.8.15"}

    收据文件.png 9. 关闭所有已经打开的终端（PowerShell 和 CMD），右键点击桌面，选择“在终端中打开”，输入 uv --version ，如果输出了类似 uv 0.8.15 (8473ecba1 2025-09-03) 这样的内容，则说明安装成功。

    2. 参考信息

    1. 配置环境变量后，需重新打开终端窗口才会生效，配置前已经打开的终端窗口不生效。

    2. 检查环境变量 Path 中是否包含实际的 uv 解压后的路径，检查字符是否敲错。

      3.2. 验证时报错：'uv' 不是内部或外部命令，也不是可运行的程序或批处理文件。

      环境变量配置问题，参考 4.1. 中的步骤排查。

      3.3. 验证时报错：uv-version :无法将"uv-version"项识别为cmdlet、函数、脚本文件或可运行程序的名称。

      命令敲错了，应该是：uv -version 而不是 uv-version，中间少了个空格。