极客工场

Appearance

共 2,388 字预计阅读约 8 分钟

Yosys 命令不在 PATH 速查：yosys command not found 与「不是内部或外部命令」 ​

更新时间：2026-10-23。FAQ 速查页，面向刚装好 Yosys（开源 Verilog 综合工具）准备在终端里跑 yosys 进交互模式、或在 Makefile 里调 yosys -p "synth_ice40" 做流水线编译的同学。典型场景：安装过程明明没报错，教程里也人人都在敲 yosys，一轮到自己终端就被 shell 顶回一句 command not found。这类问题根子几乎从不在 Yosys 二进制本身，而在 shell 的 PATH 环境变量没指向 yosys 所在的 bin 目录——装了软件不等于命令可寻址。如果命令能启动、但脚本报路径类错误（如 Can't open file），那是另一条线，见 Yosys 路径不存在速查。

本文要回答的问题 ​

  • command not found 与「不是内部或外部命令」的报错原文各长什么样，说明什么？
  • apt/brew 装的、OSS CAD Suite 解压缩的、源码自己编译的三套 Yosys 共存时，到底哪个在生效？
  • 源码 make 完就能直接敲 yosys 吗，还是必须 make install？
  • Docker 里装了 Yosys，宿主机为什么还是找不到？
  • cron、CI、nohup、IDE 集成终端里为什么"我手动敲能用、脚本里就失败"？

一、报错原文与一句话根因 ​

以下文案按两个平台常见输出整理，路径均已占位。

1. Linux / macOS 终端直接被拒：

bash
$ yosys --version
bash: yosys: command not found

$ yosys -p "read_verilog top.v; synth_ice40"
zsh: command not found: yosys

2. Windows cmd / PowerShell 里的对应形态：

text
C:\proj> yosys --version
'yosys' 不是内部或外部命令，也不是可运行的程序或批处理文件。

3. 间接形态——Makefile / 脚本里调用失败：

text
make: yosys: No such file or directory
make: *** [synth] Error 127

退出码 127 是 shell 的固定语义「命令找不到」，看到它就不用怀疑 Yosys 内部逻辑了。

一句话根因：shell 找命令只按 PATH 里列的目录逐个翻，而 Yosys 的几条主流安装路径（apt/brew 默认装到系统 bin、OSS CAD Suite 解压缩后要手动 export、源码编译后必须 make install）各有各的 PATH 约定，装完不配环境、或配了但配错目录，shell 就永远找不到那个可执行文件。 排查总原则：先用「找文件」确认 yosys 二进制真实在哪，再回头修 PATH。

二、排查决策图 ​

读图方式：从红色报错节点出发，蓝色是排查动作——先确认文件是否存在、再看 PATH 是否覆盖、再分特殊 shell 场景；命中根因走橙色修复分支，绿色为通过终点，紫色是防复发的固化动作。

fpga/ts-yosys-tool-not-in-path.md D2 示意图

这张图覆盖主流程：先定位文件、再核 PATH、区分多套共存与特殊 shell 场景。各类根因的逐条验证命令在下一节表里。

三、病因处置表 ​

报错现象根因快速验证处置
源码 make 成功后终端敲 yosys 仍 not found只编译没安装，make 产物在源码目录里，没进系统 PATH源码目录下 ./yosys --version 能跑执行 sudo make install（默认装到 /usr/local/bin），或把源码目录加进 PATH
装了 OSS CAD Suite 但命令不可用Suite 是解压缩即用的免安装包，环境脚本没 sourceSuite 目录下有 environment 脚本新开终端先 source <套件目录>/environment，或把 bin 目录写进 shell 启动文件
which 有输出但版本号比预期老apt/brew 装的旧版与 OSS CAD Suite 双套共存，PATH 顺序错which -a yosys 列出全部命中调整 PATH 顺序，想用的那套目录放前；或卸载多余的一套
Docker 容器里 yosys 能用，宿主机 not found容器文件系统与宿主机隔离，装容器里不等于装本机宿主机 which yosys 无输出宿主机另行安装；或所有编译动作都放进容器里做，Makefile 里包 docker run
交互终端能用，cron / CI / nohup 里失败非登录非交互 shell 不读 .bashrc，PATH 里没那几项sh -c 'which yosys' 复现失败配置写进 .profile / .zshenv；脚本开头显式 export PATH 或用绝对路径
Windows 下 MSYS2 终端能用、CMD 里 not foundMSYS2 的 PATH 与 Windows 原生 PATH 是两套环境CMD 里 echo %PATH% 无 MSYS2 的 bin把 MSYS2 的 usr/bin 加进 Windows 系统环境变量；或统一在 MSYS2 终端里干活
Makefile 里写死绝对路径，换机器后失败硬编码路径在两台机器上不同看 Makefile 里 YOSYS := 那一行改为 YOSYS ?= yosys 走 PATH 寻址，机器差异由各自环境变量吸收

四、三个最高频根因的修法 ​

根因一：源码编译后没 make install。 从 GitHub 拉源码自己编的同学最容易撞上这条：make 成功后 yosys 二进制就躺在源码目录里，名字叫 ./yosys，但 shell 找命令不会去翻你的源码目录。标准动作：

bash
cd <yosys 源码目录>
sudo make install          # 默认 PREFIX=/usr/local，装到 /usr/local/bin/yosys
which yosys                # 应输出 /usr/local/bin/yosys

不想用 sudo 装系统目录的，改 PREFIX 装到家目录：make install PREFIX=$HOME/.local，然后确保 $HOME/.local/bin 在 PATH 里。注意 make install 之前如果只跑过 make config-gcc 之类的配置，先确认 PREFIX 没被你改成别的奇怪位置——改了 PREFIX 又把默认目录加进 PATH，等于白配。

根因二：多套安装共存、PATH 顺序指错。 一台机器上同时有 apt 装的 yosys 0.9（老掉牙）、OSS CAD Suite 里的新版、还有早年源码编译残留，是 Linux EDA 机器的常态。诊断一条命令：

bash
which -a yosys
# /usr/bin/yosys            <- apt 装的旧版，排前面所以生效
# /opt/oss-cad-suite/bin/yosys   <- 你其实想要的新版

which -a 按 PATH 顺序列出全部命中，第一条就是实际生效的。修法是把目标目录前置到 PATH：

bash
export PATH="/opt/oss-cad-suite/bin:$PATH"

写进 ~/.bashrc 或 ~/.zshrc 末尾（注意：写前面不生效，因为启动文件后面的行可能又把 PATH 改回去）。版本对不上工程要求、综合结果与教程不一致时，问题就从环境配置转到版本层面，对照 Yosys 版本不兼容速查 处理。

根因三：非登录 shell 与 IDE 的环境落差。 这是「我终端里明明能用」一族的标准答案，背后是同一条规则：.bashrc 只在交互式 shell 启动时读，cron、CI runner、sh -c '...'、Makefile 子进程、IDE 后台任务都属于非交互场景，读不到你写进 .bashrc 的 export。修法按场景分流：给登录用户长久生效写 ~/.profile（zsh 用 ~/.zshenv，它连非交互 shell 也读）；给脚本用，就在脚本开头显式写死：

bash
#!/bin/bash
export PATH="/opt/oss-cad-suite/bin:$PATH"
yosys -p "read_verilog top.v; synth_ice40; write_json top.json"

Windows 侧的同胞坑是 MSYS2/MinGW 与原生 CMD 的 PATH 割裂：MSYS2 终端里 which yosys 能找到（因为它的 PATH 自带 /usr/bin），CMD 里同一命令报「不是内部或外部命令」。要么把 C:\msys64\usr\bin 加进 Windows 系统环境变量（改完重开 CMD 窗口才生效），要么团队统一约定只在 MSYS2 终端里跑 Yosys，不两头踩。商用工具链的同族问题与排查思路，也可对照 Quartus 命令找不到速查，两篇文章的病因轴高度重合。

五、修复后验证与防复发 ​

修完按三步验证：新开终端 which yosys 确认指向预期那套的 bin 目录；yosys -V（大写 V 打印版本号）与工程或教程要求的版本对号；拿一个真实设计跑一遍完整综合脚本，确认 read_verilog、synth、write 全流程不断。三步都过才算闭环——命令能启动但脚本报文件打不开的，转 Yosys 路径不存在速查。

顺手收一组通用排查三板斧进肌肉记忆，遇到任何「命令找不到」（不限 Yosys）都是同一路数：which -a <命令> 看 PATH 命中顺序、echo $PATH 看目录清单、find / -name "yosys" -type f 2>/dev/null（Windows 用资源管理器或 Everything 搜索）确认文件真实位置。先证明文件在，再证明 PATH 覆盖它，最后证明生效的是对的版本，三步必定位。

防复发三件事：其一，团队约定统一的安装方式与路径（要么全员 OSS CAD Suite 解到 /opt/oss-cad-suite/，要么全员包管理器），写进新人 onboarding 文档，杜绝「你源码我 apt」的混合态；其二，Makefile 里一律写 YOSYS ?= yosys 走 PATH 寻址，机器差异由各自环境变量吸收，禁止把 /home/张三/yosys/yosys 这类个人绝对路径提交进仓库；其三，CI / cron / nohup 场景一律在脚本开头显式 export PATH 或用绝对路径，不依赖任何交互 shell 的启动文件——这条做到位，「我机器上能跑、CI 上挂」这类扯皮直接绝迹。

一句话总结 ​

Yosys 命令不在 PATH 的本质是 shell 按 PATH 找命令、而 yosys 所在的 bin 目录没被覆盖：先 find 确认二进制真实位置，再 which -a 核对命中顺序与版本；源码编译的要补 make install（注意 PREFIX），OSS CAD Suite 要 source environment 或把 bin 写进启动文件，多套共存就调整 PATH 顺序，cron/CI/nohup 等非交互 shell 读不到 .bashrc 就在脚本内显式 export，Windows 下注意 MSYS2 与原生 CMD 是两套 PATH；修复后以 which、yosys -V、真实工程全综合三步验证，安装约定与 Makefile 寻址方式写进团队文档防复发。