ImportError: raise ModuleNotFoundError(

快速结论：当你在只装了 langchain-core、langgraph 和 provider 包（如 langchain-anthropic）的“精简栈”里导入 Langfuse 的 LangChain 集成回调时，会因 CallbackHandler 用 import langchain 作为版本哨兵而抛出 ImportError，最终报 ModuleNotFoundError，提示需要安装整个 langchain 伞包。优先确认是否真的缺少 langchain 伞包，以及 Langfuse Python SDK 是否低于修复版本（v5.0.1）。

适用环境：Langfuse 4.5.1 / 4.6.1；LangChain Core 1.3.3；Python 3.11；Linux（Docker）。Issue 中未提供 CUDA、显卡或 PyTorch 版本信息。

最快修复方案：升级到已在 Langfuse Python SDK v5.0.1 中修复的版本，该版本要求 langchain-core >= 1 并直接 import langchain_core，不再用伞包做版本哨兵。若暂时无法升级，可优先尝试安装 langchain 伞包作为临时绕过。

注意事项：安装整个 langchain 伞包会引入额外传递依赖、增大安装体积，且没有功能收益，只是满足旧版 CallbackHandler 的版本检查。v5.0.1 的修复路径只面向 v1 精简栈；旧版 v0 用户仍需要伞包回退和清晰报错。

问题场景

用户在使用 Langfuse 的 LangChain 集成时触发问题，具体是在导入 langfuse.langchain.CallbackHandler 时失败。复现步骤为：先执行 pip install langfuse langchain-core langchain-anthropic，再运行 python -c "from langfuse.langchain import CallbackHandler"。这种“精简栈”在现代 LangGraph 风格应用中很常见，用户有意只依赖 langchain-core 加 provider 包，而不是整个 langchain 伞包。

报错原文

ModuleNotFoundError: Please install langchain to use the Langfuse langchain integration: 'pip install langchain'

该报错由 CallbackHandler.py 中的 ImportError 分支触发：

raise ModuleNotFoundError(
    "Please install langchain to use the Langfuse langchain integration: 'pip install langchain'"
)

原因分析

在 Langfuse 4.5.1 / 4.6.1 的 langfuse/langchain/CallbackHandler.py（约 40–85 行）中，代码先用 import langchain 作为版本哨兵，再根据 langchain.__version__ 是否以 "1" 开头决定走 v1 还是 v0 分支。问题在于 v1 分支里的实际导入全部来自 langchain_core（例如 langchain_core.agents、langchain_core.callbacks、langchain_core.documents、langchain_core.messages、langchain_core.outputs），并不需要 langchain 伞包本身。因此，只装了 langchain-core 的精简栈会因为 import langchain 这一步失败而进入 except ImportError，抛出需要安装 langchain 的错误。根本原因是把伞包当作版本哨兵，而 v1 的实际依赖已由 langchain_core 提供。

环境排查

确认 Langfuse Python SDK 版本是否为 4.5.1 或 4.6.1（存在该问题的版本）；检查是否已升级到 v5.0.1 或更高。
确认 Python 版本（Issue 中为 3.11）。
确认 langchain-core 版本（Issue 中为 1.3.3），以及是否满足修复版本要求的 langchain-core >= 1。
确认当前依赖栈是否只包含 langgraph、langchain-core 和 provider 包（如 langchain-anthropic、langchain-openai），而没有安装 langchain 伞包。
确认运行环境（Issue 为 Linux / Docker），以及是否存在容器内依赖与本地不一致的情况。

解决步骤

确认当前安装的 Langfuse 版本。若为 4.5.1 或 4.6.1，说明处于受影响版本区间。
首选方案：将 Langfuse Python SDK 升级到已在 v5.0.1 中修复的版本。该版本要求 langchain-core >= 1，内部直接 import langchain_core，不再依赖 langchain 伞包作为版本哨兵（见 langfuse/langfuse-python#1940）。
临时绕过（可优先尝试）：在精简环境中安装 langchain 伞包，执行 pip install langchain，以满足旧版 CallbackHandler 的版本检查；但需注意这会引入额外传递依赖和安装体积。
若为旧版 v0 用户，仍需保留伞包回退路径，并确保报错信息清晰提示需要安装 langchain<1.0 以使用旧版集成。
修改或升级后重新运行复现命令：python -c "from langfuse.langchain import CallbackHandler"，确认不再抛出 ModuleNotFoundError。

验证方法

在只安装 langfuse、langchain-core、langchain-anthropic（不装 langchain 伞包）的环境中，运行 python -c "from langfuse.langchain import CallbackHandler"。若升级到 v5.0.1 后导入不再报错，说明精简栈路径已恢复正常；若仍报错，检查 langchain-core 是否满足 >= 1，并确认实际加载的 Langfuse 版本。