本文详解因 Python 版本不兼容导致 adk 命令无法识别的根本原因及解决方案，重点指出 google-adk 包仅支持 Python 3.11+，使用低版本（如 3.8）安装会导致可执行脚本未正确注册到 PATH。

本文详解因 python 版本不兼容导致 `adk` 命令无法识别的根本原因及解决方案，重点指出 `google-adk` 包仅支持 python 3.11+，使用低版本（如 3.8）安装会导致可执行脚本未正确注册到 path。

Google ADK（Agent Development Kit）是一个面向 AI Agent 开发的官方工具包，其 CLI 工具 adk 在安装后应全局可用。但许多开发者在运行 adk web 或 adk run multi_agent_tool 时遇到 Command 'adk' not found 错误——这通常并非路径配置或虚拟环境激活问题，而是由 Python 解释器版本不兼容引发的静默安装失败。

? 根本原因：Python 版本不满足最低要求

google-adk 当前（v0.5+）明确要求 Python ≥ 3.11。若系统默认 Python 为 3.8（常见于 Ubuntu 22.04、macOS 系统自带版本等），即使在 venv 中执行 pip install google-adk，pip 仍可能因依赖冲突跳过安装 CLI 入口脚本（即 adk 可执行文件），导致命令不可用。

✅ 正确安装步骤（推荐）

1. 确认并切换至 Python 3.11+

   # 检查当前 Python 版本
   python --version  # 若输出 < 3.11，请更换
   # 推荐使用 pyenv 或系统包管理器安装 Python 3.11+
   # 例如（Ubuntu）：
   sudo apt update && sudo apt install python3.11 python3.11-venv python3.11-dev

2. 创建并激活兼容版本的虚拟环境

   

   Google Search Grounding 3

   通过 Gemini 搜索落地（主）和 Custom Search JSON API（备）进行 Google 网页搜索。用途：(1) 附引用的综合回答（落地搜索），(2) 含摘要的原始链接结果，(3) 图片搜索。希伯来语支持极佳。优于内置 web_search (Perplexity)。

   下载

   python3.11 -m venv adk-env
   source adk-env/bin/activate  # Linux/macOS
   # adk-env\Scripts\activate  # Windows

3. 显式使用对应 pip 安装（关键！）

   pip3.11 install google-adk  # ✅ 强制使用 Python 3.11 的 pip
   # 或确保 pip 指向正确版本：
   python3.11 -m pip install google-adk

4. 验证安装

   adk --version  # 应输出类似 "adk version 0.5.0"
   adk web        # 启动本地开发服务器

⚠️ 注意事项

• ❌ 不要仅依赖 pip install google-adk（尤其当 pip 关联旧版 Python 时）；
• ✅ 始终通过 python3.x -m pip 或 pip3.x 显式指定解释器；
• ? 安装成功后，adk 脚本位于虚拟环境的 bin/（Linux/macOS）或 Scripts/（Windows）目录下，该路径会随 venv 自动加入 PATH；
• 若仍报错，请检查 which adk 或 where adk 是否返回路径，并确认虚拟环境已激活。

? 总结

Command 'adk' not found 是典型的“安装看似成功、实则入口缺失”问题。核心解法是严格匹配 Python 版本约束——放弃 3.8/3.9/3.10，统一升级至 Python 3.11 或更高版本，并在安装时显式绑定 pip。此举不仅能解决命令缺失，还能避免后续运行时因类型提示、异步语法等引发的兼容性异常。