nextpnr 找不到模块或芯片包报错速查
更新时间：2026-10-23。速查页，面向刚把 yosys + nextpnr 开源 FPGA 流程跑起来的同学。典型症状：综合明明过了，
nextpnr-ice40一启动就红——ERROR: No chip database for chip ...，或者报你写的--package不在库里，再或者 Python 脚本直接ModuleNotFoundError，而你确认这块板子型号没记错。
报错原文与一句话根因
nextpnr 系「找不到」类报错常见三种面孔：
ERROR: No chip database for chip 'lp8k' specified on command line
ERROR: package 'tq144' is not valid for chip 'hx8k'
ERROR: failed to open chipdb file '/usr/local/share/nextpnr/ice40/chipdb-hx4k.bin'
Traceback (most recent call last):
File "place.py", line 3, in <module>
ModuleNotFoundError: No module named 'nextpnrpy'
ERROR: top module 'top_uart' not found in design一句话根因：nextpnr 布局布线要同时满足「器件数据库里有这颗芯片」「封装名与库里逐字符对上」「数据库文件路径能被打开」「Python 插件能被内嵌解释器加载」「-top 指定的模块在 yosys 输出的 JSON 里真实存在」五个条件，任何一个断了都会以「找不到」的形式爆出来。它不是你的设计丢了，而是环境、参数或命名对不上。排查按「器件 → 封装 → 路径 → Python → top 名」顺序短路即可。
五大病因速查表
| 报错形态 | 最可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| No chip database for chip | 器件参数写错（--lp384/--hx8k 拼错或系列搞混） | nextpnr-ice40 --help 看支持列表 | 改成库里真实存在的器件代号 |
| No chip database for chip | 自编 nextpnr 时该系列 chipdb 没编进去 | ls <prefix>/share/nextpnr/ice40/ 看有哪些 .bin | 重编时带上对应 -DARCH 与 ice40 chipdb |
| package is not valid for chip | --package 字符串与数据库封装名大小写/写法不符 | 报错行上方通常会列出合法封装 | 逐字符改成列出的名字（如 tq144:4k） |
| failed to open chipdb file | --chipdb 路径写错，或文件没装全 | ls 该路径直接确认 | 修正路径或重装 nextpnr 数据文件 |
| ModuleNotFoundError | nextpnr 内嵌 Python 找不到 site-packages | python3 -c "import sys; print(sys.path)" 对比 | 设 PYTHONPATH 或把插件装进 nextpnr 用的那个 Python |
| top module not found in design | -top 参数与 yosys JSON 里的顶层名不符 | 打开 .json 搜 "top" 或看 modules 键 | 让 yosys -p "synth_ice40 -top xxx" 与 nextpnr 参数一致 |
排查决策流程
照这张图自上而下短路排查，第一个答「否」的节点就是根因。图中红色是入口现象，蓝色是排查动作，绿色是判定通过，橙色是修复动作，紫色是防复发收尾：
读法：器件与 chipdb 是启动第一关，封装名第二关，路径第三关，top 名最后一关。绝大多数案例倒在「器件代号想当然」和「封装名大小写」这两格。
逐条排查步骤
第一步，确认器件代号真实存在。 跑 nextpnr-ice40 --help，输出里会列出该二进制支持的器件（如 --lp384、--lp1k、--lp8k、--hx1k、--hx4k、--hx8k、--up5k、--u1k、--u2k、--u4k）。注意 lp 和 hx 是两个不同系列——板子是 iCE40-HX8K 你写 --lp8k，就是 No chip database。代号要按芯片丝印系列选，不是按直觉选。
先解释一下 nextpnr 的查找模型，后面每一步为什么查这些就顺了：nextpnr 启动时按命令行的器件代号，到安装目录的 chipdb 集合里找对应的数据库文件并加载；然后从库中该器件的条目里取合法封装列表，拿你给的 --package 去做精确字符串匹配；最后用 -top 的名字到 yosys 传入的 JSON 设计里找顶层模块。三层查找任何一层 miss，报出来的都是「找不到」家族的错，所以排查本质是逐层确认「这一层的符号表里有没有你要的那一项」。
第二步，确认 chipdb 真的编进去了。 官方预编译包通常全系列齐全；自己从源码编 nextpnr 时，如果只配了某几个器件，其余系列的 .bin 数据库文件不会生成。直接看安装目录：
ls /usr/local/share/nextpnr/ice40/
# 正常应看到 chipdb-lp384.bin chipdb-hx8k.bin chipdb-up5k.bin ... 一串缺哪个就在编译时把对应器件加进 ICE40_DEVICES 配置重新 make install。这条对 nextpnr-ecp5 / nextpnr-nexus 同理，只是目录名换掉。
第三步，封装名逐字符核对。 --package 不是自由文本，必须是该器件数据库里登记过的封装名。报错信息 package 'tq144' is not valid for chip 'hx8k' 之后通常会列出合法值（如 cb132、tq144:4k、ct256 等）。注意 tq144 与 tq144:4k 是两个不同条目——冒号后缀也是名字的一部分，漏了就无效。
第四步，chipdb 路径。 显式传 --chipdb 的场景（自定义数据库或调试新器件），确认路径真实存在、有读权限、且文件不是 0 字节（下载中断的 .bba/.bin 会以 failed to open 或解析错的形式爆）。相对路径按当前工作目录解析，Makefile 里切换过目录的尤其要查。
第五步，Python 插件找不到。 报 ModuleNotFoundError: No module named 'nextpnrpy' 这类错，问题是 nextpnr 内嵌的 Python 解释器的 sys.path 里没有插件目录。先确认 nextpnr 编译时启用了 Python 支持（nextpnr-ice40 --help 里有 --run 选项即启用），再把插件装进同一个 Python 环境，或启动前 export PYTHONPATH=<nextpnr插件目录>。系统里有多个 Python 版本时这条最容易踩——你 pip install 装进了 3.11，而 nextpnr 内嵌的是 3.9。
第六步，top 模块名对齐。 ERROR: top module 'top_uart' not found in design 是 yosys 输出的 JSON 里根本没有这个模块名。常见两种：一是综合时 synth_ice40 -top xxx 写的是另一个名字（比如 top 而不是 top_uart）；二是顶层设计在综合阶段被整个优化掉了（所有输出悬空）。打开 yosys 生成的 .json，看 modules 下的键名到底是什么，让两边一致；顺带确认综合日志里 top 没被 flatten 成空壳。
修复后验证
- 重跑完整命令，确认报错消失且进入正常的布局布线日志（
Info: Placing.../Info: Routing...字样出现），而不是换了一个新错。 - 日志开头会打印加载的器件与封装，核对与你板子丝印完全一致。
- 跑通后顺势执行
icepack生成比特流并烧录一次，确认整条链闭环，避免「这次参数改对了、下次又漂回去」。
常见坑
- lp/hx/up 系列搞混：同为 8K 规模，
--lp8k和--hx8k是两颗不同芯片，数据库不通用。 - 封装名想当然：照着开发板 Wiki 抄
tq144，实际数据库条目叫tq144:4k，差一个后缀就 invalid。 - 自编漏系列：编译时图快只编了 hx8k，换块 up5k 板子就 No chip database。
- Python 版本错配：内嵌解释器版本与 pip 装的版本不是同一个，插件永远 import 不到。
- top 名两处漂移：RTL 改了顶层名，Makefile 里 yosys 的
-top和 nextpnr 的参数只改了一处。
防复发清单
- Makefile 里把器件三件套（
--器件、--package、chipdb 路径）集中定义成变量，一处改全链改。 - yosys 的
-top与 RTL 顶层 module 名用同一个变量传给两段流程，杜绝两处漂移。 - 自编 nextpnr 时把要用的器件系列一次编全，chipdb 目录纳入版本说明。
- Python 插件依赖写进工程 README，注明用哪个 Python 版本装。
- CI 里加一个最小冒烟：拿一颗空设计跑通
yosys → nextpnr → icepack，参数写错十秒内爆掉，不用等真设计。
这一篇在知识体系里的位置
同族报错：Yosys 找不到模块速查（上游综合阶段的同名问题，先综合后布线，先查那篇再查本篇）；nextpnr 资源放不下速查（器件参数对、但设计超容的另一类报错）；跨工具对照可看 Quartus 找不到模块速查，商业套件靠 .qsf 清单、开源流程靠命令行参数与 chipdb，病因轴相通。
一句话总结
nextpnr 找不到模块或芯片包的本质是器件数据库、封装名、chipdb 路径、Python 环境、top 模块名五处必须同时与命令行参数对上：按「器件代号 → chipdb 是否编入 → 封装名逐字符 → 文件路径 → -top 对齐」短路排查，--help 列表与报错给出的合法值是最权威的核对依据，再把参数三件套收进 Makefile 变量、CI 跑空设计冒烟，这类报错五分钟内必收敛。