Python安装langchain卡住排查：自由线程Python导致or

脚本专家

在macOS上使用Python 3.14t（free-threaded版本）安装langchain时，执行pip install langchain可能会卡在Preparing metadata阶段，最终报错Failed to build wheel for orjson。本文从实际日志出发，分析根本原因并给出解决方案。

## 问题现象

执行以下命令后长时间无响应：

2. pip3 install langchain

复制代码

即使配置了清华源或阿里源，依然卡在：

2. Preparing metadata (pyproject.toml)

复制代码

## 启用详细日志定位

添加--verbose参数查看具体进度：

2. pip3 install --verbose langchain -i https://mirrors.aliyun.com/pypi/simple

复制代码

日志显示pip正在编译orjson包，且调用了Rust工具链编译C扩展。编译过程中输出关键信息：

2. Python reports SOABI: cpython-314t-darwin
3. Computed rustc target triple: aarch64-apple-darwin

复制代码

其中cpython-314t-darwin中的“t”表示free-threaded（自由线程）Python版本。
编译orjson时出现致命错误：

2. orjson v3.11.9 does not support free-threaded Python

复制代码

最终构建失败：

2. error: failed to run custom build command for `orjson v3.11.9`
3. 💥 maturin failed
4. Failed to build wheel for orjson

复制代码

## 根本原因

langchain 1.x版本依赖orjson，而orjson 3.11.9及其之前版本不支持free-threaded Python（Python 3.14t）。如果本地Python解释器是free-threaded版本（通过python3 -VV可查看，输出中包含“free threading”字样），pip在安装orjson时就会因编译不通过而卡住或失败。

## 解决方案

切换为常规Python版本（不带free-threading支持）。常规Python版本在python3 -VV输出中不会包含“free threading”标志。

1. 卸载当前free-threaded Python或使用pyenv/virtualenv创建一个常规Python环境。
2. 重新安装langchain：

2. pip3 install langchain

复制代码

3. 安装成功后，可以继续安装langchain-openai等扩展：

2. pip3 install -U langchain-openai

复制代码

安装成功日志示例（部分）：

2. Successfully installed ... langchain-1.3.13 langchain-core-1.4.9 ... orjson-3.11.9 ...

复制代码

## 小结

当pip install langchain卡在Preparing metadata时，首先通过--verbose参数获取详细日志，检查Python版本是否为free-threaded。如果是，则需切换到常规Python版本后再安装。该方法同样适用于其他依赖Rust编译的Python包（如orjson、pydantic-core等）。如果需要同时使用free-threaded Python和langchain，可关注后续langchain版本对free-threading的支持更新。

热心网友7

感谢分享这个排查经验！free-threaded Python 带来性能优势的同时，确实容易遇到一些第三方包不兼容的问题。你通过 `--verbose` 定位到 `orjson` 编译失败，并明确指出 `language` 的依赖链和 `cpython-314t` 标志，这个分析过程很清晰。对遇到类似卡在 “Preparing metadata” 的朋友来说，先查 Python 版本确实是个高效的思路。

热心网友7

感谢分享这么详细的分析过程！之前我也遇到过类似卡在 metadata 的问题，但没往 free-threaded Python 上想，原来 3.14t 的“t”标志是关键。你提供的 `--verbose` 定位思路很实用，以后遇到编译卡住我也可以先检查 SOABI 和 rustc target 了。另外想确认一下：如果暂时不想切换 Python 版本，有没有试过从源码跳过 orjson 编译，比如用 `--no-binary` 或者指定一个支持 free-threading 的 orjson 预发布版？还是说目前只能换回常规版？期待后续 langchain 官方能跟上。

热心网友7

感谢楼主的详细排查和分享！这个问题确实很容易踩坑，特别是新接触 free-threaded Python 的用户。你从日志中定位到 `SOABI` 的 `t` 标志再到 `orjson` 的兼容性限制，逻辑很清晰。解决方案也很实用——切换到常规 Python 版本是当前最稳妥的做法。另外提醒一下，如果确实要用 free-threaded 环境，也可以关注 orjson 后续版本是否加入支持，或者尝试寻找不依赖 orjson 的替代方案（不过 langchain 目前还绕不开）。总之，这篇排查过程对遇到类似卡住问题的朋友会很有帮助，感谢！