[解决方案] AstrBot 插件依赖安装失败：uv 工具缺失问题

[yaohewoma]

AstrBot 插件依赖安装失败：uv 工具缺失问题解决方案

📋 问题描述

在特定 Windows 环境下，安装 AstrBot 插件时出现依赖安装失败，错误码为 2。此问题与 AstrBot 核心代码无关，而是由于特定环境配置导致 AstrBot 尝试使用 uv 工具安装依赖，但系统中缺少 uv 可执行文件。

典型错误日志

[INFO] Upgrading pip using index: `https://mirrors.aliyun.com/pypi/simple`
[INFO] Installing uv using index: `https://mirrors.aliyun.com/pypi/simple`
[INFO] Installing requirements using index: `https://mirrors.aliyun.com/pypi/simple`
D:\AstrBot\venv\Scripts\python.exe: No module named uv
[WARN] requirements install failed with `https://mirrors.aliyun.com/pypi/simple.`
Retrying with `https://pypi.org/simple...`
D:\AstrBot\venv\Scripts\python.exe: No module named uv
[ERROR] Failed to install dependencies from requirements.txt.

或

uv._find_uv.UvNotFound: Could not find the uv binary in any of the following locations:
 - D:\AstrBot\venv\Scripts
 - C:\Users\Administrator\AppData\Local\Programs\Python\Python310\Scripts
 - D:\AstrBot\venv\lib\site-packages\bin
 - C:\Users\Administrator\AppData\Roaming\Python\Python310\Scripts

影响范围

• 操作系统: Windows 10/11
• AstrBot 版本: v4.22.3+（特定环境）
• Python 版本: 3.10+
• 触发场景: 安装插件时自动安装依赖

---

🔍 问题原因分析

重要说明

此问题与 AstrBot 核心代码无关。AstrBot 核心代码使用的是标准 pip 进行依赖管理（详见 astrbot/core/utils/pip_installer.py）。

根本原因

在特定 Windows 环境下，AstrBot 会尝试使用 uv 工具来安装插件依赖，而不是使用标准的 pip。这可能是由于：

1. Python 环境被全局修改 - 系统中的 Python 配置或 pip 配置被其他工具修改
2. 环境变量配置 - 存在影响 pip 行为的环境变量
3. 虚拟环境被污染 - venv 中的 pip 被替换或配置被修改
4. 系统级 Python 钩子 - Windows 系统中存在全局的 Python 启动钩子

为什么需要 uv

uv 是一个高性能的 Python 包管理工具，AstrBot 在特定环境下会尝试使用它来加速依赖安装。但 uv 包含两部分：

• Python 模块 - 通过 pip install uv 安装
• 可执行文件 (uv.exe) - 需要单独安装

仅安装 Python 模块是不够的，必须同时有可执行文件。

---

✅ 解决方案

方案一：使用 WinGet 安装 uv（推荐 ⭐）

WinGet 是 Windows 自带的包管理器，可以自动安装 uv 并配置环境变量。

步骤 1：安装 uv

以管理员身份打开 PowerShell 或 CMD，执行：

winget install --id=astral-sh.uv -e

安装成功输出示例：

Found uv [astral-sh.uv] Version 0.11.3
Successfully installed
Path environment variable modified; restart your shell to use the new value.
Command line alias added: "uvx"
Command line alias added: "uv"
Command line alias added: "uvw"

步骤 2：查找 uv 安装位置

where uv

典型输出：

C:\uv\uv.exe
C:\Users\Administrator\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_Microsoft.Winget.Source_8wekyb3d8bbwe\uv.exe

步骤 3：复制 uv.exe 到 AstrBot 虚拟环境

copy "C:\uv\uv.exe" "D:\AstrBot\venv\Scripts\"
copy "C:\uv\uvx.exe" "D:\AstrBot\venv\Scripts\"

注意：请根据你的实际安装路径修改命令中的路径。

步骤 4：重启 AstrBot

关闭并重新启动 AstrBot，插件依赖安装应该能正常工作了。

---

方案二：手动下载 uv 可执行文件

如果 WinGet 无法使用，可以手动下载 uv。

步骤 1：下载 uv

访问 uv 的 GitHub Releases 页面：
https://github.com/astral-sh/uv/releases

下载对应系统的版本：

• Windows x64: uv-x86_64-pc-windows-msvc.zip
• Windows ARM64: uv-aarch64-pc-windows-msvc.zip

步骤 2：解压并复制

解压下载的 zip 文件，将 uv.exe 和 uvx.exe 复制到 AstrBot 的虚拟环境 Scripts 目录：

D:\AstrBot\venv\Scripts\

步骤 3：重启 AstrBot

---

方案三：使用 PowerShell 脚本安装 uv

# 安装 uv 到系统
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 找到安装位置
where uv

# 复制到虚拟环境
copy "%USERPROFILE%\.local\bin\uv.exe" "D:\AstrBot\venv\Scripts\"
copy "%USERPROFILE%\.local\bin\uvx.exe" "D:\AstrBot\venv\Scripts\"

---

🔧 验证安装

检查 uv 是否正确安装

# 检查系统 uv
uv --version

# 检查虚拟环境 uv
D:\AstrBot\venv\Scripts\uv.exe --version

成功输出示例：

uv 0.11.3

测试插件安装

重启 AstrBot 后，尝试安装一个插件，观察是否还会出现依赖安装失败的错误。

---

❓ 常见问题 FAQ

Q1: 这是 AstrBot 的 bug 吗？

A: 不是。AstrBot 核心代码使用的是标准 pip（详见 astrbot/core/utils/pip_installer.py）。此问题是由特定 Windows 环境配置导致的，AstrBot 在这些环境下会尝试使用 uv 而不是 pip。

Q2: 为什么 pip install uv 不够？

A: pip install uv 只安装了 Python 模块，但 AstrBot 需要调用 uv.exe 可执行文件。必须通过 WinGet、官方安装脚本或手动下载获取可执行文件。

Q3: 复制 uv.exe 后仍然报错？

A: 请检查：

1. 是否同时复制了 uvx.exe
2. 是否复制到了正确的虚拟环境目录（venv\Scripts\）
3. 是否重启了 AstrBot
4. 复制的 uv.exe 是否与系统架构匹配（x64/ARM64）

Q4: 如何找到我的 AstrBot 虚拟环境路径？

A: 默认路径通常在 AstrBot 安装目录下：

D:\AstrBot\venv\Scripts\

或在启动 AstrBot 时查看日志中的 Python 路径。

Q5: Linux/Mac 系统会遇到此问题吗？

A: 此问题主要出现在特定 Windows 环境下。Linux/Mac 用户通常不会遇到此问题。如果遇到，可以使用以下命令安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

Q6: 如何确认 AstrBot 使用的是哪个包管理器？

A: 查看 AstrBot 启动日志，搜索 pip 或 uv 相关日志。正常情况下 AstrBot 使用 pip，但在特定环境下会尝试使用 uv。

Q7: 有没有办法让 AstrBot 不使用 uv？

A: 此问题是由环境配置导致的，不是 AstrBot 的可配置选项。如果希望 AstrBot 使用标准 pip，建议检查并清理 Python 环境配置，找出导致 AstrBot 尝试使用 uv 的原因。

---

🔍 环境检查建议

如果希望找出根本原因，建议检查以下内容：

1. 检查 pip 配置

pip config list

2. 检查环境变量

Get-ChildItem Env: | Where-Object { $_.Name -like "*PIP*" -or $_.Name -like "*PYTHON*" }

3. 检查虚拟环境

# 查看 venv 中的 pip
D:\AstrBot\venv\Scripts\pip.exe --version

# 查看 venv 配置文件
Get-Content D:\AstrBot\venv\pyvenv.cfg

4. 检查全局 Python 配置

检查以下位置是否有异常配置：

• %APPDATA%\pip\pip.ini
• %LOCALAPPDATA%\pip\pip.ini
• C:\ProgramData\pip\pip.ini

---

📊 环境信息

测试环境

操作系统：

• 版本：Windows 11 专业版
• 版本号：25H2
• 操作系统版本：26200.8037
• 安装日期：2026/3/12
• 系统类型：64 位操作系统，基于 x64 的处理器

硬件配置：

• 处理器：AMD Ryzen 7 5700X 8-Core Processor (3.40 GHz)
• 内存：16.0 GB
• 设备名称：台式机

软件环境：

• AstrBot 版本: v4.22.3+
• Python 版本: 3.10+
• uv 版本: 0.11.3+ (推荐最新版)
• 问题类型: 环境特定问题，非 AstrBot 核心代码问题

适用范围

• 操作系统: Windows 10/11 (x64/ARM64)
• 触发条件: 特定 Windows 环境下，使用 Launcher 或旧版安装器部署 AstrBot

---

🔗 参考链接

• uv 官方文档
• uv GitHub Releases
• AstrBot 官方文档
• AstrBot GitHub Issues

---

📝 总结

问题本质

在特定 Windows 环境下，AstrBot 会尝试使用 uv 作为包管理器，但虚拟环境中缺少 uv 的可执行文件（uv.exe），导致插件依赖安装失败。

解决核心

1. 安装 uv 到系统（WinGet/手动/脚本）
2. 找到 uv.exe 位置
3. 复制 uv.exe 到 AstrBot 虚拟环境
4. 重启 AstrBot

推荐方案

WinGet 安装是最简单可靠的方式，自动处理环境变量和路径配置。

重要提醒

此问题与 AstrBot 核心代码无关，而是由特定环境配置导致。如果希望找出根本原因，建议检查 Python 环境配置。

---

📚 附录：问题排查全过程记录

背景

此问题最初出现在一位用户的 Windows 电脑上，表现为使用 Launcher 或旧版 Windows 安装器部署 AstrBot 时，插件依赖安装都会失败，错误码为 2。（注：桌面端不受此 uv 问题影响）

排查过程

第一阶段：初步分析错误日志

观察到的现象：

• 安装插件时出现 ModuleNotFoundError: No module named 'uv'
• 日志显示 [INFO] Installing uv using index: ...
• 错误码 2，表示依赖安装失败

初步判断：

• AstrBot 尝试使用 uv 安装依赖
• 但系统中缺少 uv 的可执行文件

第二阶段：尝试安装 uv

尝试 1：使用 pip 安装 uv

pip install uv

结果： 失败

• pip 安装的 uv 只有 Python 模块
• 缺少 uv.exe 可执行文件
• AstrBot 仍然报错 No module named 'uv'

发现：

• pip install uv 安装的包位于 D:\Python\Lib\site-packages\uv
• 但 AstrBot 虚拟环境在 D:\AstrBot\venv\
• 虚拟环境中没有 uv.exe

第三阶段：手动复制 uv 到虚拟环境

尝试 2：复制 uv 模块到虚拟环境

xcopy "D:\Python\Lib\site-packages\uv" ".\venv\Lib\site-packages\uv" /E /I

结果： 部分成功

• uv 模块复制成功
• 但 AstrBot 报错 uv._find_uv.UvNotFound
• 仍然缺少 uv.exe 可执行文件

关键发现：

• uv 包含两部分：Python 模块 + 可执行文件
• 仅复制模块不够，必须有 uv.exe

第四阶段：安装 uv 可执行文件

尝试 3：使用 WinGet 安装 uv

winget install --id=astral-sh.uv -e

结果： 成功安装 uv 到系统

• 安装位置：C:\uv\uv.exe
• 同时安装了 uvx.exe

尝试 4：复制 uv.exe 到虚拟环境

copy "C:\uv\uv.exe" "D:\AstrBot\venv\Scripts\"
copy "C:\uv\uvx.exe" "D:\AstrBot\venv\Scripts\"

结果： 成功！

• AstrBot 插件安装正常
• 依赖安装不再报错

第五阶段：深入分析根本原因

疑问： 为什么 AstrBot 会尝试使用 uv？

调查 1：检查 AstrBot 核心代码

• 查看 astrbot/core/utils/pip_installer.py
• 发现 AstrBot 核心代码使用的是标准 pip
• 没有使用 uv 的逻辑

调查 2：检查 requirements.txt

• AstrBot 核心依赖中没有 uv
• 说明 uv 不是 AstrBot 的必需依赖

调查 3：检查启动脚本

• 查看 main.py、runtime_bootstrap.py
• 没有发现自动安装 uv 的逻辑

关键发现：

• AstrBot 核心代码确实只使用 pip
• 但特定环境下会尝试使用 uv
• 这是环境特定问题，不是代码问题

第六阶段：确认问题范围

测试： 在多个 AstrBot 部署方式上测试

方式 1：AstrBot Launcher（启动器）

• 问题： 启动时即报错，无法正常运行
• 错误： [INFO] Installing uv... 后 No module named uv
• 原因： 启动器尝试使用 uv 安装依赖，但缺少 uv.exe

方式 2：旧版 Windows 安装器（PowerShell 脚本）- 最终使用的方案

• 问题： 启动时即报错，无法正常运行
• 错误： 同启动器，缺少 uv.exe
• 注意： 旧版 Windows 安装器已被官方标记为"不推荐"，但在某些环境下可能是唯一可行的方案

方式 3：AstrBot 桌面端（Desktop）

• 启动： 正常，可以正常运行
• 问题： 安装插件时报错
• 错误： 插件依赖安装失败: 安装失败，错误码：2 和 failed to set global default subscriber
• 原因： 插件依赖冲突（与 uv 无关，是另一个问题）
• 结论： 桌面端不受 uv 问题影响，但可能有其他插件安装问题

结论：

• 问题与特定 AstrBot 部署方式有关（Launcher 和旧版安装器受影响，桌面端不受影响）
• 问题与特定 Windows 环境有关
• 可能是 Python 环境配置、环境变量、或系统级钩子导致

关键发现总结

1. AstrBot 核心代码使用 pip

   • 代码位置：astrbot/core/utils/pip_installer.py
   • 依赖文件：requirements.txt 中没有 uv

2. 特定环境会触发 uv 使用

   • 原因尚不明确
   • 可能是环境变量、pip 配置、或系统级修改

3. 解决方案有效

   • 安装 uv 并复制到虚拟环境可以解决问题
   • 这是绕过方案，不是根本解决方案

4. 问题性质

   • 环境特定问题
   • 不是 AstrBot 的 bug
   • 但可能影响其他用户

版本缺陷记录

受影响版本：

• AstrBot v4.22.3+
• 测试过的部署方式：
  • ✅ AstrBot Launcher（启动器）v0.2.1+ - 受影响（启动时即报错）
  • ✅ 旧版 Windows 安装器（PowerShell 脚本）0.3.0 - 受影响（启动时即报错）
  • ❌ AstrBot 桌面端（Desktop）v4.22.2+ - 不受 uv 问题影响（启动正常，但可能有其他插件安装问题）

缺陷描述：
在特定 Windows 环境下，AstrBot 会尝试使用 uv 工具安装插件依赖，但：

1. 系统中可能没有安装 uv
2. 或 uv 安装不完整（缺少 uv.exe 可执行文件）
3. 导致插件依赖安装失败，错误码 2

缺陷影响：

• 无法正常安装插件
• 插件依赖无法自动安装
• 影响用户体验

临时解决方案：

• 手动安装 uv 并复制到 AstrBot 虚拟环境（详见上文解决方案）

建议修复：

• AstrBot 应该检测 uv 是否存在，如果不存在则回退到使用 pip
• 或在文档中明确说明需要手动安装 uv
• 或在安装过程中自动安装完整的 uv（包括 uv.exe）

建议的后续行动

对于用户：

• 使用本文档的解决方案安装 uv
• 或检查 Python 环境配置找出根本原因

对于 AstrBot 开发者：

• 考虑检测 uv 是否存在，提供 fallback 到 pip 的机制
• 或在文档中说明可能需要手动安装 uv

对于社区：

• 收集更多案例，找出触发此问题的具体环境条件
• 完善解决方案文档

---

希望这个解决方案能帮助到遇到同样问题的朋友！如有疑问或更好的方案，欢迎在评论区讨论。

最后更新时间：2026-04-08