nextpnr 找不到依赖库报错速查：shared library 缺失、LD_LIBRARY_PATH 与 ABI 版本错位怎么办
更新时间：2026-10-23。FAQ 速查页，属于 FPGA 工具报错排错系列。nextpnr 找不到依赖库报错最迷惑的地方在于：安装过程一路绿灯，
nextpnr-ice40 --version一敲却直接崩在动态链接器手里——报错文案不是 nextpnr 自己打的，而是系统的 ld.so / dyld 在加载阶段就把它拦下了。病因轴有五条：编译时链接的库运行时不在搜索路径、依赖包根本没装、发行版升级后 ABI 版本号变了、conda/venv 环境库与系统库抢位置、以及芯片数据库 chipdb 与二进制版本不匹配。命令本身不在 PATH 的姊妹篇见 Yosys 命令不在 PATH 速查，版本口径类同族病见 nextpnr 版本不匹配速查。
本文要回答的问题
error while loading shared libraries: libboost_program_options.so.1.74.0是什么意思，缺的库去哪装？- macOS 上报
dyld: Library not loaded: /usr/local/opt/...，自编译的 nextpnr 为什么起不来？ - 系统升级（Ubuntu 20.04 升到 22.04）后原来能跑的 nextpnr 突然报缺库，为什么？
- 装了 conda 之后 nextpnr 开始加载错误的库版本，怎么隔离？
libleftpad chipdb类报错或 chipdb 段错误，和二进制是什么关系？
一、报错原文与典型现象
以下路径与版本号均为占位，报错风格按真实 ld.so / dyld 输出给出。
1. Linux：共享库根本不存在或不在搜索路径。
$ nextpnr-ice40 --version
nextpnr-ice40: error while loading shared libraries:
libboost_program_options.so.1.74.0: cannot open shared object file:
No such file or directory这是 ld.so 在加载阶段的报错，nextpnr 的主函数一行都没跑到。libboost_program_options.so.1.74.0 这个文件名里的 1.74.0 是编译时链接器记下的 SONAME，运行时必须在库搜索路径里找到完全同名的文件，大版本不一致都不行。
2. macOS：自编译链接了 /usr/local 或 Homebrew 路径，运行时解析不到。
$ nextpnr-ecp5 --gui
dyld[12345]: Library not loaded: /usr/local/opt/qt@5/lib/QtWidgets.framework/Versions/5/QtWidgets
Referenced from: /usr/local/bin/nextpnr-ecp5
Reason: image not found
Abort trap: 6dyld 报错的格式和 Linux 不同但语义一样：Mach-O 二进制里写死了库的完整安装路径，目标路径下没有那个文件就直接 Abort trap。Homebrew 升级后 opt/qt@5 目录被挪动或清掉是典型触发点。
3. 库在，但版本符号不匹配。
nextpnr-ice40: symbol lookup error: nextpnr-ice40:
undefined symbol: _ZN5boost15program_options...能加载到库、但库里没有编译时用的那个符号——装了一个错误版本的 boost（如编的时候 1.74、装的是 1.81），属于 ABI 错位的另一种表现。
二、现象 → 病因 → 处置速查表
| 报错现象 | 缺的是哪一层 | 一判据 | 处置方向 |
|---|---|---|---|
error while loading shared libraries: libboost_*.so.X.XX.0 | 系统 boost 运行库未装 | ldd 对应行显示 not found | 装 libboost-program-optionsX.XX 等运行包 |
缺 libQt5Widgets.so.5 | Qt5 运行库未装 | 报错只在带 --gui 时出现 | 装 qt5 运行库，或重编译去掉 GUI 选项 |
macOS dyld: Library not loaded: /usr/local/opt/... | Homebrew 库路径失效 | otool -L 列出 /usr/local/opt 旧路径 | 重装对应 brew 包或重编译 |
| 发行版升级后报缺旧版 SONAME | 系统库 ABI 升级 | 报错里版本号比系统现有版本旧 | 装旧版兼容包或重编译链接新库 |
装 conda 后报 undefined symbol | conda 库抢先加载 | ldd 显示库指向 conda 目录 | 退出 conda 环境运行，或调 LD_LIBRARY_PATH 顺序 |
| 自编译放 /usr/local 后 ld.so 找不到 | 运行时搜索路径未覆盖 /usr/local/lib | ldd 大片 not found | LD_LIBRARY_PATH=/usr/local/lib 或写 ld.so.conf |
缺 libeigen 相关 | 头文件库装错包 | 编译期报错而非运行期 | 装 libeigen3-dev 开发包 |
| 启动即段错误且提及 chipdb | chipdb 与二进制版本不匹配 | nextpnr --version 可跑、加载器件时崩 | 重生成 chipdb 或对齐 nextpnr 版本，见版本不匹配篇 |
ldd 全部已解析仍报缺库 | 插件/dlopen 路径缺失 | 主库全 found、运行到功能点才报 | strace 跟踪 openat 找真实加载路径 |
三、排查决策树
分诊只看两件事：报错出自哪个加载器（ld.so / dyld / 运行期符号解析），缺的库属于哪一条线。下图颜色含义：红=报错入口与命中的根因，蓝=分诊动作，绿=验证通过，橙=修复动作，紫=防复发沉淀。
读这张图抓住一个分叉：ldd（Linux）或 otool -L（macOS）是所有分支的总入口，先把「到底缺哪个文件、解析到哪条路径」看清楚再动手。not found 行指向 /usr/lib 系的是系统包没装（红-左），库文件明明在磁盘上但 ldd 找不到的是搜索路径问题（蓝-中），指向 conda 目录的是环境打架（红-右中）。任何橙色修复动作做完都要回到绿色节点：nextpnr --help 能完整输出、再跑一次最小设计布线确认闭环，最后落到紫色节点把这次的依赖清单写进装机文档。
四、逐条排查展开
第一步永远是 ldd / otool -L。 Linux 上 ldd $(which nextpnr-ice40) 会把全部动态依赖列出来，not found 结尾的行就是缺的库；macOS 对应命令是 otool -L /usr/local/bin/nextpnr-ecp5。这一步把「装没装」和「路径对不对」两个问题一次看清，比盲装任何包都快。
系统依赖包没装：装运行包，不是开发包。 Debian/Ubuntu 系缺 boost 时按报错里的 SONAME 装精确版本：
sudo apt install libboost-program-options1.74.0 \
libboost-filesystem1.74.0 libboost-thread1.74.0只在 --gui 模式下才需要 Qt5 运行库（libqt5widgets5 等），纯命令行用不到——如果你根本不开 GUI，更干净的做法是重编译时 -DBUILD_GUI=OFF，从源头砍掉这条依赖。eigen3 是纯头文件库，缺它的报错只会出现在编译期，装 libeigen3-dev 即可，运行时不会缺 eigen。
库在但搜索路径不覆盖：三种修法按优先级。 自编译装到 /usr/local 后 ldd 大片 not found，说明 /usr/local/lib 不在 ld 搜索配置里。临时验证用 LD_LIBRARY_PATH=/usr/local/lib nextpnr-ice40 --version；长期方案是把 /usr/local/lib 写进 /etc/ld.so.conf.d/ 下一个 conf 文件再 sudo ldconfig；只给单个用户用就在 shell 配置里 export LD_LIBRARY_PATH。macOS 没有 ldconfig，Homebrew 库路径挪动后最稳的修法是 brew reinstall 对应包再重编译 nextpnr，让 dyld 路径重新对齐。
发行版升级 ABI 错位：装兼容包或重编译。 Ubuntu 20.04 升 22.04 后 boost 从 1.74 变 1.81，旧 SONAME 文件被清掉，一切链接旧版的二进制同时阵亡。两条路：装发行版提供的旧版兼容包（如果有）；或者干脆重编译 nextpnr——git pull 后重新 cmake && make，让它链接新系统库。自己编译的工具链在系统大版本升级后重编译一遍是常规维护动作，不算返工。
conda/venv 环境打架：退出环境再跑。 conda 激活时会把自己 lib 目录塞进搜索路径前面，里面的 boost/Qt 版本往往和系统编译时对不上，症状就是 undefined symbol。最直接的修法：conda deactivate 后在干净 shell 里跑 nextpnr；必须在 conda 里跑就把 nextpnr 也装进同一环境，让编译与运行环境一致。
chipdb 不匹配：崩在加载器件而不是启动。 chipdb 的 .bba/.bin 文件是与 nextpnr 源码版本强绑定的，用旧版 chipdb 配新版二进制（或反过来）会在指定 --chipdb 或自动加载时段错误。症状与缺库相似但 ldd 全绿——这时对齐版本重新生成 chipdb，判定细节与版本矩阵见 nextpnr 版本不匹配速查。
五、预防与纪律
- 装机文档写死依赖清单：
apt list --installed | grep -E "boost|qt5|eigen"的输出版本号随文档归档，新机器照单装。 - 自编译工具链与系统大版本升级绑定：升级发行版/Homebrew 大版本的同一动作里重编译 yosys/nextpnr，不留旧 ABI 二进制。
- conda 环境与 EDA 工具链隔离：跑 nextpnr 的终端不开 conda base 自动激活，避免库路径被静默改写。
- GUI 按需编译：服务器/CI 环境一律
-DBUILD_GUI=OFF，砍掉 Qt5 这条最容易断的依赖线。 - chipdb 与二进制同批生成：升级 nextpnr 源码就重跑 chipdb 构建，不混用两批产物，同主题细节见 Yosys 依赖缺失速查。
这一篇在知识体系里的位置
本篇是 FPGA 工具报错排错簇中 nextpnr 侧「依赖库缺失」的分流页：命令本身找不到看 Yosys 命令不在 PATH 速查（nextpnr 同型病同理）；chipdb 与二进制版本口径冲突看 nextpnr 版本不匹配速查；Yosys 侧同主题对照看 Yosys 依赖缺失速查。
一句话总结
nextpnr 找不到依赖库报错先跑 ldd（macOS 用 otool -L）看 not found 行定位缺的库：指向系统路径的是运行包没装，按 SONAME 版本号装对应 boost/Qt5 运行包、GUI 用不上就 -DBUILD_GUI=OFF 砍掉 Qt 依赖；库文件在但搜不到是 /usr/local/lib 没进搜索路径，配 LD_LIBRARY_PATH 或 ld.so.conf；报错版本号比系统旧是发行版升级 ABI 错位，装兼容包或重编译；指向 conda 目录的是环境库抢先，退出环境再跑；库全解析仍崩在加载器件是 chipdb 与二进制不匹配，对齐版本重生成；根治靠装机依赖清单、系统升级即重编译、conda 与 EDA 环境隔离三件套。