搞 Python 的人十个里有九个都见过ModuleNotFoundError这个红字而No module named orjson又是里面特别能折腾人的一个。它经常藏在pip install某一个大包的时候突然蹦出来前面刚装了一堆依赖眼看就要成功了结果给你一记当头棒喝。还有更隐蔽的情况依赖装得干干净净一跑程序照样报这个错查了半天才发现是环境串了。这篇文章就把这个报错从头到尾拆一遍从报错本身是什么含义到 orjson 为什么会被卷入安装过程再到各种场景下的具体解法最后附上一份我实际排查时的完整记录和踩坑速查表。不管你是刚入门 Python 的初学者还是已经在用 FastAPI、Pandas 这类重度依赖库的开发者按着这篇文章的思路走基本都能一次解决。1. 报错链路拆解No module named orjson 到底怎么来的1.1 从报错信息反推 Python 的模块查找机制先把这句话翻译成人话ModuleNotFoundError: No module named orjson的意思是Python 解释器在执行 import 语句时按照自己的一套搜索路径找了一圈没找到名字叫orjson的模块于是抛出了异常。Python 找模块的路径顺序大致是当前脚本所在目录、PYTHONPATH环境变量指定的路径、标准库目录、site-packages 里安装的第三方库目录。你可以用几行代码随时看自己环境里到底有哪些搜索路径import sys for idx, path in enumerate(sys.path): print(idx, path)如果 orjson 已经装上了但解释器还是找不到那就说明报错的这个解释器和安装包时用的解释器不是同一个。这就是后面要反复强调的一个重点报错是哪个 Python 解释器在跑它到底去哪里找包先搞清楚这个问题就解决了一半。再补充一个和 3.6 版本相关的背景知识ModuleNotFoundError是 Python 3.6 开始从ImportError里细分出来的子类。所以你在老代码里可能还会看到ImportError: No module named orjson这是历史版本差异含义完全一样排查思路也完全相同。1.2 报错位置不同问题性质完全不同同样是这个报错出现在不同阶段根因可能差得很远。我一般先分两类一类是安装时报错另一类是运行时报错。安装时报错最典型的情况是你在执行pip install 某个包的时候pip 去下载和构建这个包包里的 setup 脚本或构建钩子里import orjson但当前环境里没有于是一整条安装链路直接中断。这种情况在安装从 GitHub 拉下来的源码包、或者本地开发中尚未发布成 wheel 的包时特别常见因为源码包往往需要在构建阶段执行 Python 代码去读取配置或生成文件。运行时报错更普遍pip install已经成功结束甚至pip list里也能看到 orjson但一执行python main.py就报错找不到模块。这种问题的八成原因是环境错位——系统里有多个 Python或者虚拟环境没激活安装是装到 A 解释器里了运行时却用的是 B 解释器。如果运行时报错发生在虚拟环境内部还有一种隐蔽情况项目目录里恰好有一个文件叫orjson.py或者你自己写过一个同名模块。这时候 Python 会在 sys.path 的当前目录优先命中的是自己的文件而不是 site-packages 里的真 orjson于是要么导入失败要么导入了一个缺各种属性的假模块。这个问题排查起来非常迷惑后面实操部分我会专门展开。2. 为什么装个包会牵扯出 orjson依赖链背后的安装机制2.1 orjson 是什么谁离不开它先给不认识 orjson 的读者补个背景。orjson 是一个用 Rust 编写的高性能 JSON 序列化库官方文档的基准测试里它序列化和反序列化的速度通常是标准库json的好几倍。因为性能亮眼很多追求速度的第三方库会把它作为可选或必选的依赖。Web 框架里FastAPI 和 Starlette 生态对 orjson 的支持做得比较深开启后 JSON 响应可以直接让 orjson 处理高并发场景下能把序列化这块的 CPU 开销压下去不少。数据处理和爬虫领域里也有不少库在解析大量 JSON 时选择 orjson 做底层加速。所以当你pip install某个库时pip 看了一眼这个库的install_requires或依赖声明发现它import orjson或者声明了orjson某个版本就会顺手把 orjson 拉进安装列表。正常情况下你根本不会注意到但一旦网络抖动、版本冲突、或者走的源里没有对应系统的二进制包orjson 就成了最显眼的那个报错点。需要说明的是orjson 并不是所有场景的必需品纯标准库写的项目完全可以不碰它。它大多是被间接依赖带进来的这也是很多人报错时一头雾水的原因——明明自己从来没主动装过 orjson怎么就被它卡住了。2.2 pip 解析依赖与构建时的暗坑pip 的依赖解析逻辑在普通场景下是透明的读元数据、算版本、下载、安装。但这里有两个暗坑是我排查时重点看的。第一个暗坑是源码包构建阶段依赖。很多库在发布时只提供 sdist源码包没有提供当前系统对应的 wheel 包。pip 要安装这种包就会先构建构建工具的配置文件比如 pyproject.toml 里的build-system.requires里如果写了一堆构建依赖而这些依赖又没提前装进环境构建就会在中途报错。如果那个库的构建脚本里恰好引到了 orjson报错信息就会包含No module named orjson。第二个暗坑是版本回溯。pip 在某些情况下为了满足整个依赖树的版本要求会先安装一个 A 版本之后发现和另一个包冲突又降级成 B 版本。这个过程中如果某个环节的 wheel 不可用pip 可能把已装好的包卸载掉但依赖它的其他模块还在别的地方继续引用最终导致运行时报No module named orjson。看起来是玄学实际是版本解析留下的烂摊子。提示遇到这种诡异的依赖链问题先别急着单个装 orjson。看清楚完整报错上下文里 pip 正在处理哪个包大概率真正的根因在那个包身上而不是 orjson 本身。除此之外Python 版本兼容性也值得留意。orjson 这类带 Rust 扩展的库对不同 Python 版本的支持窗口是有限的。如果你用的是比较老的 Python 版本pip 在解析时可能找不到匹配的预编译 wheel就会尝试从源码编译而源码编译需要 Rust 工具链和一堆构建依赖环境里没有的话又是一串连环报错。3. 对症下药从临时修复到根除的四个方案3.1 方案一先把 orjson 装进当前环境最直接的办法就是手动安装缺失的模块。打开终端执行pip install orjson如果当前环境里已有多个 Python 或虚拟环境建议用更精确的写法直接指定用哪个解释器安装python -m pip install orjson这里用python -m pip而不是裸pip install是有讲究的。裸pip对应的是 PATH 里排在最前面的那个 pip它可能指向 A 解释器而你直接跑python xxx.py用的可能是 B 解释器。python -m pip保证安装动作和你之后运行代码用的解释器是同一个。装完之后验证一下python -c import orjson; print(orjson.__version__)能打出版本号说明这个环境下 and 可以正常 import基础问题解决。如果这里还报错说明环境本身有问题直接跳到方案四用虚拟环境隔离。3.2 方案二升级 pip 与 setuptools修复依赖解析如果你是在安装某个大包的过程中报错装完 orjson 之后很可能还会在下一个依赖上再次卡住因为根本问题是 pip 的依赖解析逻辑或构建工具太旧。这种情况下先把基础工具升级一轮python -m pip install --upgrade pip setuptools wheel升级之后再重新执行之前失败的安装命令很多时候就不会再报同样的问题了。为什么升级这几样东西有用旧版本 pip 对 PEP 517/518 构建协议的支持不完善遇到采用新式 pyproject.toml 声明的包构建过程容易出幺蛾子。setuptools 版本太老则可能导致某些包的元数据读取异常间接造成依赖缺失的假象。wheel 包如果没有及时更新在本地构建和缓存利用上也可能有兼容性问题。这类问题的典型特征是报错信息里的缺失模块每次不一样这次是 orjson上一次可能是 pydantic再上一次是 attrs。看到这种“不固定缺失模块”的规律基本可以断定不是 orjson 的锅而是工具链老化升级完立刻见效。3.3 方案三锁定版本与 requirements.txt 基建orjson 本身也在持续迭代不同版本对不同系统的支持有差异。如果安装时 Network 波动导致下载了一半或者某次缓存坏了常规的pip install orjson可能反复失败。这时候可以显式指定版本安装pip install orjson3.9.10指定版本有两个好处一是避开最新版可能的兼容性问题二是走 pip 的缓存机制时同一个版本的元数据可以直接复用减少重复下载。具体版本号可以去 PyPI 的 orjson 页面查挑一个稳定且和你的 Python 版本匹配的即可。更推荐的做法是把这个依赖写进项目的 requirements.txtorjson3.9.10 fastapi0.111.0 uvicorn0.30.1然后统一安装pip install -r requirements.txt把依赖版本锁死是避免“这次能跑、下次重装就报错”的关键。现实世界里直接pip install 包名装出来的是一个不固定版本过了半年再装可能就是另一个版本连带依赖也跟着变报错只是时间问题。锁版本虽然不能完全避免依赖冲突但至少给了你一个稳定可复现的起点。3.4 方案四用虚拟环境隔离依赖污染这一条是长期的根治方案也是最推荐在生产环境或正经项目里使用的方案。Python 项目最忌讳的就是把所有依赖都堆在全局环境里时间一长和系统自带的 Python 包相互污染或者不同项目对同一个包要求不同的版本直接冲突到不可收拾。标准做法是给每个项目建独立虚拟环境python -m venv venv创建之后激活Windows 下venv\Scripts\activateLinux 和 macOS 下source venv/bin/activate激活之后命令行提示符前面会出现(venv)字样这时候再执行 pip install所有包都会装进这个虚拟环境跟系统环境完全隔离。跑程序时只要保证是在同一个终端会话里用同一个解释器就不会再出现“装到了 A、跑在 B”的错位。如果连 venv 都用得不顺还可以考虑 conda 或者 uv 这类更现代的环境管理工具。conda 的优势在于不仅管 Python 包还能管不同版本的 Python 解释器uv 则是这两年热度飙升的工具安装快、并发度高、依赖解析准确主打的就是一个省心。工具的选择看个人习惯但“每个项目一套环境、依赖显式声明”这个原则是通用的。注意不要轻易直接用sudo pip install orjson往系统 Python 里猛装包尤其是 Linux 发行版自带的 Python。系统包管理器管理的那一套环境被 pip 动过之后很容易出问题重则把系统组件搞坏。遇到权限问题优先考虑用户级安装或虚拟环境。4. 一次完整的排查与修复实操记录4.1 事件复现与初始判断上周我在一台新配的 Linux 服务器上部署一个基于 FastAPI 的服务克隆代码后按照 README 执行pip install -r requirements.txt日志一路滚得很顺利装到某个阶段突然中断核心报错就是ModuleNotFoundError: No module named orjson因为 requirements.txt 里并没有 orjson我第一反应是某个间接依赖引到了它。于是没急着去下载 orjson而是先打开完整日志往回翻找到 pip 此刻正在处理的那个包发现是一个内部数据处理库它的元数据里声明了对 orjson 的依赖。初始判断有两个方向一是这个库的依赖没被 pip 正确解析到二是解析到了但下载环节出了问题。由于日志里能看到 pip 已经下载了不少包网络基本通我倾向于先把依赖解析这块排查清楚。4.2 逐层排查的具体过程第一步确认当前环境里有没有 orjsonpip show orjson返回为空确认缺失。第二步确认当前 Python 解释器路径和 pip 指向的是不是同一个解释器which python which pip python -m pip --version实际输出里python指向/usr/bin/python3pip也指向对应的解释器排除了环境错位。但既然报错发生在安装中途而不是运行阶段环境错位本来就不是主要嫌疑对象。第三步检查 pip 版本python -m pip --version发现服务器上带的 pip 还是 20.3 版本这个版本对新版 pyproject.toml 构建协议的支持确实不够完善属于老毛病了。于是先升级工具链python -m pip install --upgrade pip setuptools wheel升级完成之后重新执行pip install -r requirements.txt这次没有在 orjson 上报错。这里要说明一下升级 pip 不是必然能解决所有情况但在这个案例里老版本 pip 对某些依赖元数据的解析存在缺陷导致 orjson 的依赖没有被正确拉取和安装所以报错才会出现在安装阶段。升级后 pip 的依赖解析能力提升这个问题就消失了。4.3 修复验证与收尾重新安装完成后做三件事验证第一确认依赖树完整pip list | grep orjson能看到 orjson 且版本号符合预期。第二确认可以正常导入python -c import orjson; print(orjson.__version__)输出版本号无异常。第三启动服务做一次端到端验证。服务起来之后调一个返回 JSON 的接口响应正常之前的报错没有再出现。最后我把修复动作沉淀进了项目文档部署第一步升级 pip 工具链、requirements.txt 显式锁定关键依赖、必要时用虚拟环境隔离。这套操作下来后续再换机器部署就没在这个环节上踩过第二次坑。5. 常见问题排查表与独家避坑技巧5.1 高频症状对照表整理这份速查表的时候我把这些年见过的报错场景大致归了几类方便你对症下手症状可能的根因首选排查动作运行代码时报缺少 orjson但之前没主动装过间接依赖未正确安装pip show orjson缺失则安装pip install 过程中报缺少 orjson依赖解析异常或构建阶段 import升级 pip/setuptools 后重装安装时下载很慢或超时失败网络原因或当前源不稳定切换国内镜像源重试import 报错但 pip show 显示已安装多个解释器环境错位which python对比which pip项目目录里存在 orjson.py 文件同名文件遮蔽真实模块rename 该文件清空pycache安装 orjson 时提示需要 Rust 编译平台无预编译 wheel 包安装 Rust 工具链或更换平台升级 pip 后安装成功但运行仍报错虚拟环境未激活或激活了错误环境source venv/bin/activate后重装镜像源这行多说一句如果你在国内网络环境默认的 PyPI 源偶尔会抽风装大包或者带二进制扩展的包时尤其明显。换一个国内镜像能省不少时间pip install orjson -i https://pypi.tuna.tsinghua.edu.cn/simple这种切换只是把下载源改了不影响包的内容和兼容性。如果项目有统一的依赖文件也可以在 pip.conf 或环境变量里把默认源改掉一劳永逸。5.2 排查路径与几个我踩过的坑排查这个报错我的建议是严格按住以下顺序来不要跳步看清报错是发生在pip install阶段还是程序运行阶段这两个方向不同。which python和which pip同时跑确认解释器是否统一。pip show orjson看当前环境到底装没装装了是什么版本。python -c import orjson直接试探导入看报错是否复现。如果导入报错且 pip 显示已安装去项目目录找有没有叫 orjson.py 的文件或检查sys.path有没有被改过。第 5 步是很多人栽跟头的地方。我自己遇到过一次项目根目录下不知道谁放了一个工具脚本叫orjson.py从网上复制下来想改改用结果这个文件直接把真正安装的 orjson 给“遮蔽”了。Python 导入模块时优先看的是当前脚本目录于是每次 import 进来的都是这个半吊子文件自然各种报错。排查了大半天最后用python -c import orjson; print(orjson.__file__)一看路径指向了项目根目录才恍然大悟。这个命令在排查所有“已安装但 import 不对”的情况下都很好用因为 print 出来的文件路径能直接告诉你解释器到底加载了哪个文件。另外还有一个习惯值得养成pip install装完第三方库后顺手用import验证一次。这一步耗时几乎可以忽略但能立刻发现问题避免在“以为装好了”的错觉里继续往深了写代码。很多人是在写了几百行业务代码之后才被 import 报错打断回头才发现当初那个包根本没装上返工成本极高。如果你在团队协作项目里还有一个小建议把环境版本信息固化下来。一个项目里至少要有 requirements.txt更多人会选择加一个包含完整依赖锁定版本的 requirements-lock.txt甚至直接用 Poetry 或 PDM 这类工具管理依赖。锁定版本的意义在于你的同事、未来的你、CI 服务器任何人在任何时候重装环境得到的结果都与开发时一致不会凭空多出或缺少某个依赖。orjson 这次报错本质上就是环境一致性和依赖解析链的问题解决思路也适用于其他任何No module named xxx报错。最后再分享一个我实际验证过的小技巧当你怀疑是 pip 缓存导致安装结果不对时可以先执行pip cache purge清空缓存再重新安装。这个操作可以解决一部分“下载了但内容不完整”引起的诡异问题成本低、无副作用。我后来在多个项目里都把它列在“环境重装”的标准操作里效果一直很稳定。