Yosys: the open synthesis framework behind open source FPGA and ASIC flows

What Yosys is for, and who ends up using it

Yosys is a framework for RTL synthesis tools, not a finished product with a fixed feature set. The README describes it as having extensive Verilog-2005 support and a basic set of synthesis algorithms for various application domains. That wording matters: the value is in the assembly, not in any single algorithm.

The people who get the most out of it fall into two groups. The first writes synthesis scripts: a sequence of passes that reads a design, elaborates it, converts processes to netlist elements, maps to gates, and writes a netlist out. The second extends the C++ code base with new passes when the existing ones do not cover a target. If you are in neither group, you are probably better served by a flow built on top of Yosys than by Yosys itself.

The README is explicit that Yosys can be adapted to perform any synthesis job by combining existing passes using synthesis scripts and adding passes as needed. That is a design commitment: the project ships primitives and expects you to compose them.

The pass pipeline and RTLIL, the two ideas that explain everything

Everything in Yosys is a command applied to an in-memory design. The README's walkthrough shows the shape of it: read and elaborate with read and hierarchy, dump the internal representation with write_rtlil, lower always blocks with proc, optimize with opt, map to gates with techmap, and emit Verilog with write_verilog.

The intermediate representation is called RTLIL, and write_rtlil prints it to the console. This is the part of the design that is genuinely useful in practice: when a design fails to map, the RTLIL dump is where you find out whether the frontend produced what you expected or whether a pass removed something you needed. Most synthesis tools do not expose that layer.

The pass set is not a monolith. proc and techmap do different jobs at different levels of abstraction, and opt is applied more than once because lowering creates new opportunities. Nothing in the README suggests a canonical order beyond the example it gives; the sequence is yours to choose, which is also the source of most mistakes.

Installing Yosys: binary suite first, source when you need to extend it

The README treats the binary software suite as the easiest route, because it contains all required dependencies and related tools. Two options are named: the free OSS CAD Suite, downloaded from the oss-cad-suite-build releases page, and the commercial Tabby CAD Suite, for which you contact YosysHQ for an evaluation license and download link. The README also notes that many Linux distributions provide Yosys binaries, some more up to date than others, and tells you to check with your package manager.

Building from source starts with the submodules, which the README says are required libraries:

git clone https://github.com/YosysHQ/yosys.git
cd yosys
git submodule update --init

Prerequisites are a C++20 compiler plus GNU Flex, GNU Bison (>=3.8), CMake (>=3.28), Make or another CMake generator, and Python (>=3.11). Readline, libffi, Tcl and zlib are used if available but are optional. Graphviz and Xdot are what the show command needs to display schematics. On Ubuntu 22.04 LTS the README gives this exact line:

sudo apt-get install gawk git make python3 lld bison clang flex \
	libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
	graphviz xdot

The README flags that Ubuntu 22.04 LTS caps CMake at 3.22 through apt, below the 3.28 minimum, and suggests sudo snap install cmake --classic. Configuration uses a separate build directory, and the quick release install is:

cmake -B build . -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel $(nproc)
sudo cmake --install build --strip

Build variables can be set one-off with -D, for example -DYOSYS_WITHOUT_ZLIB=ON, or persistently through a CMakeUserPresets.json file in the repository root. Tests live in the tests subdirectory and run through the test target, which the README says needs gawk, a recent iverilog, and gtest.

A first synthesis run, interactive and scripted

Start the shell from the build directory. The prompt is yosys>, and help lists every command while help <command> prints details for one of them.

./build/yosys

Inside the shell, the README reads and elaborates a design from the test suite, then asks for the top module explicitly:

yosys> read -sv tests/simple/fiedler-cooley.v
yosys> hierarchy -top up3down5
yosys> write_rtlil

The write_rtlil output is the design in Yosys's internal format, printed to the console. If you want a picture instead, show uses xdot, and show -format ps -viewer gv renders postscript through gv. The rest of the README's sequence lowers processes and maps to gates:

yosys> proc; opt
yosys> techmap; opt
yosys> write_verilog synth.v

The same job as a script file is what most people actually keep in version control:

read -sv tests/simple/fiedler-cooley.v
hierarchy -top up3down5
proc; opt; techmap; opt
write_verilog synth.v

Run it with ./yosys synth.ys. The README's walkthrough ends by noting that ABC matters at this point if it is enabled in the build, which is where gate-level mapping to a standard cell library enters the picture.

Where Yosys stops: no bitstream, no vendor primitives, no free lunch

The README never promises a path from Verilog to a configured device. It gives you a netlist and a scriptable framework. Turning that netlist into a bitstream for a specific part is the job of the flows built on top, which is why the repository carries example directories named for boards and vendors (examples/basys3, examples/gowin, examples/igloo2, examples/intel, examples/mimas2, examples/anlogic) rather than a single unified backend.

The SystemVerilog story is also more conditional than the first line of the README suggests. Yosys uses the sv-elab and slang libraries to provide comprehensive SystemVerilog support, and it supports what the README calls an informally defined synthesizable subset of SystemVerilog in IEEE 1800-2017 or IEEE 1800-2023. The phrase informally defined is doing real work here. If your design leans on verification constructs, classes, or anything outside that subset, expect to find the boundary yourself. The README also points out that industry-grade SystemVerilog and VHDL parsers are a Tabby CAD Suite feature, which is the clearest statement in the document that the open build's frontend coverage is not the same as the commercial one.

Finally, the pass model has a cost. A wrong pass order can silently produce a netlist that simulates differently from the source, and Yosys will not tell you. The opt passes are not semantics-preserving in the way a reader might assume; they are preserving with respect to the design after elaboration, which is a narrower guarantee.

Yosys compared with a vendor synthesis tool

The obvious alternative is the synthesis engine that ships with an FPGA vendor's toolchain. The difference is not quality, it is the contract. A vendor tool takes your HDL, applies a fixed, tuned mapping to that vendor's primitives, and hands you a bitstream. You influence it through attributes and constraints, not through the algorithm sequence.

Yosys inverts that. You get the algorithm sequence, and you get the RTLIL dump when you want to see what a pass did. What you do not get from the README is a vendor primitive library for your part; that comes from a flow layered on top, or from a technology library under techlibs. If your goal is to ship a design to a specific commercial FPGA with the least friction, the vendor tool is the shorter path and Yosys is the wrong tool. If your goal is to understand or change what synthesis does, or to target something no vendor supports, the trade goes the other way.

The same split applies to formal work. The README points users interested in formal verification to SBY, a separate front-end, rather than describing formal flows inside Yosys itself. Treat them as two projects that share an engine, not one product.

Licence, upgrade cost, and what a release cadence implies

Yosys is free software under the ISC license, which the README describes as GPL compatible and similar in terms to the MIT license or the 2-clause BSD license. That matters if you plan to embed or redistribute it. Third-party software distributed alongside it is under compatible licenses, and the README directs you to the abc and libs subdirectories for their terms. If you redistribute a binary build, those subdirectory licences are the ones to read; the ISC terms on Yosys itself do not cover them. This is not legal advice, and the COPYING file in the repository root is the authoritative text.

On upgrades, the repository shows a steady release cadence: v0.67 on 2026-07-09, v0.68 on 2026-08-05, and v0.69 on 2026-09-09, with the last push on 2026-09-22. Frequent releases are good for bug fixes and bad for script stability, because a pass sequence tuned against one version can behave differently against the next. Pinning a version in CI is the practical response, and the OSS CAD Suite release page is where a pinned binary comes from if you do not want to build.

Building from source has its own recurring cost. The README requires CMake >= 3.28, which is above what several long-term-support distributions ship, so a source build often means bringing your own CMake before you bring your own compiler.

Editorial conclusion

Adopt Yosys if you need a scriptable, inspectable synthesis step for an open FPGA or ASIC flow, or if you plan to write your own passes against the C++ code base. Do not adopt it expecting a one-command path from Verilog to a programmed board; the README points to the OSS CAD Suite and to vendor-specific example directories such as examples/basys3 and examples/gowin for that, and each of those carries its own toolchain requirements. Before committing, verify two things: that your source is inside the synthesizable subset the frontends accept, and that the pass sequence in your script is one you can read back from the RTLIL dump when something does not map.

Frequently asked questions

Official sources

1. License: ISC
2. Project website
3. README
4. Releases
5. YosysHQ/yosys on GitHub