ModuleNotFoundError: No module named ‘proxy_server’

快速结论：该报错发生在通过 pipx、uv-tool 或虚拟环境安装 litellm[proxy] 后，直接运行 litellm --version（或其它走 proxy_cli.run_server 入口的子命令）时触发。优先排查方式：确认是否为 1.72.6 至 1.97.0.dev2 范围内的版本，并转移到已修复的 main 分支版本验证。

适用环境：Linux (x86_64)、Python 3.11/3.12、pipx 1.x、LiteLLM 1.95.0、1.96.0、1.96.2、1.97.0.dev2（同期 1.72.6+ 亦受影响）；不涉及 Windows。

最快修复方案：暂无确认的一步修复方案。Issue 中明确可用的办法是：使用包含修复提交 f9b86b253a 的 main 分支源码安装，或等待后续发布 tag；否则可单独执行 python -c "from litellm.proxy import proxy_server" 确认模块存在，以绕过 CLI 入口的导入缺陷。

注意事项：该问题与 fastapi-0.140.7 触发的另一条 traceback 路径不同，且对应的 PR #35858 未合并；在修复版本正式发布前，所有依赖 litellm --version 的 CI 冒烟检查、安装验证、包门禁均会受影响。本方案仅确认模块在磁盘上存在，不能保证 CLI 层立即恢复。

问题场景

用户在干净 pipx 环境执行 pipx install 'litellm[proxy]' 后，运行裸命令 litellm --version 触发 traceback。报错栈经由 click 路由到 proxy_cli.run_server，即使传入 --version，run_server 内部的裸导入也在版本短路返回前被无条件求值。CLI 其余能力（如 litellm config-validate、litellm completion）可能同样受影响，但 Issue 中未验证。

报错原文

Traceback (most recent call last):
  File ".../litellm/proxy/proxy_cli.py", line 1018, in run_server
    from proxy_server import (
ModuleNotFoundError: No module named 'proxy_server'

原因分析

可能原因：litellm/proxy/proxy_cli.py:1018 附近（以及旧版对应区域）在 run_server 的 except ImportError 分支中，为“用户 git clone 的 litellm”场景执行裸导入 from proxy_server import (...)。当包为正常安装（pipx/venv）时，该导入块因 proxy extras 未进入裸入口点的 sys.path 而抛出 ModuleNotFoundError，导致 --version 在任何 pipx/uv-tool 安装下不可用，尽管安装时已指定 litellm[proxy]。Issue 作者直接验证了 python -c "from litellm.proxy import proxy_server; print(proxy_server.__file__)" 成功，证明模块在磁盘上，CLI 只是从裸入口点找不到它。Issue 被关闭为 #11836 的重复问题，确认同一回归跨越 1.72.6 → 1.97.0.dev2 多个版本。

环境排查

Python 版本：3.11、3.12（已确认）；3.10 及以下、3.13 未提供证据，不确定。
LiteLLM 版本：1.72.6、1.95.0、1.96.0、1.96.2、1.97.0.dev2（已确认受影响）。
安装方式：pipx 1.x、uv-tool、虚拟环境（venv）均可能触发同一根因。
fastapi 版本：0.140.7 产生的 traceback 变体属于另一代码路径（PR #35858 未合并），不要混淆排查方向。

解决步骤

先确认当前安装版本：litellm --version 若已 traceback，跳过此步，依据安装记录确认版本号在受影响范围内。
从包含修复提交 f9b86b253a 的 main 分支源码重新安装（该提交在 main 上，但尚未出现在任何 release tag 中）。
若无法切换 main，可单独运行 python -c "from litellm.proxy import proxy_server; print(proxy_server.__file__)" 验证 proxy_server 模块确实存在。
关注 #11836 动态，待修复随正式版本发布后升级替换。

验证方法

成功标志：litellm --version 直接打印版本号并以 exit code 0 退出，不再经过 run_server 的导入逻辑；或升级到包含 f9b86b253a 的版本后 CLI 恢复正常。Issue 中建议的修复方向是：将 from proxy_server import (...) 移到 if version is True: ... return 提前返回之后，或用 try/except 保护该导入块避免在已安装包上抛裸 ModuleNotFoundError。