Windows 下 uv 命令无法识别：Python 工具路径配置详解

Windows 下 uv 命令无法识别：Python 工具路径配置详解

问题背景

最近在 Windows 环境下使用 pip install uv 安装了新一代极速 Python 包管理器 uv。安装成功后尝试在 PowerShell 中运行 uv 命令，却遇到了如下报错：

uv : 无法将'uv'项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。

这是典型的环境变量未配置导致系统无法识别命令行工具。

---

一、确认 uv 是否已安装

可以使用以下命令查看 uv 是否已被 pip 正常安装：

pip show uv

你将会看到类似这样的输出：

Name: uv Version: 0.7.6 Location: C:\Users\<用户名>\AppData\Roaming\Python\Python311\site-packages

特别注意其中的 Location 路径，它的上一级目录通常会包含可执行文件 uv.exe，也就是：

C:\Users\<用户名>\AppData\Roaming\Python\Python311\Scripts\

---

二、临时使用 uv（快速绕过）

你可以直接运行完整路径的 uv.exe 来验证工具是否可用：

& "C:\Users\<你的用户名>\AppData\Roaming\Python\Python311\Scripts\uv.exe"

输出如下，说明安装成功：

An extremely fast Python package manager. Usage: uv.exe [OPTIONS] <COMMAND> ...

---

三、永久解决：将 uv 加入系统环境变量

操作步骤：

1. 打开'环境变量'配置界面：
   • Win + S 输入：环境变量 → 选择 '编辑系统环境变量' → 点击右下角'环境变量'按钮。
2. 修改 Path 环境变量（推荐修改'用户变量'）：
   • 找到 Path → 点击'编辑' → '新建'。
3. 添加 Scripts 路径：
   • 输入如下路径：

     C:\Users\<你的用户名>\AppData\Roaming\Python\Python311\Scripts\
     

4. 保存并重启终端：
   • 点击'确定'保存所有设置，并 重启 PowerShell 窗口。

再次执行：

uv --version