SymbiYosys tutorial · Chapter 2 of 10 · 15 min

Install SymbiYosys on Linux

This chapter installs SymbiYosys, Yosys and every proof engine the tutorial uses from one dated release of the OSS CAD Suite. Everything goes into your home directory, so no step needs sudo except the optional package install for later chapters.

What do you need before you start?

Linux on an x86-64 machine. The commands and output in this tutorial come from Ubuntu 24.04.4 LTS. The suite also has builds for Linux arm64, macOS and Windows, which this tutorial does not cover.
At least 3.7 GB of free disk space. The table shows what the tutorial stores in your home directory and how much space each part takes.

What the tutorial stores	Disk space
The extracted suite (Step 2)	2.6 GB
The work folders of Chapters 3 to 6	44 MB
riscv-formal and the checks of NERV (Chapter 7)	771 MB
PicoRV32 and its checks (Chapter 8)	29 MB
The EQY example and its checks (Chapter 9)	203 MB
Total, at the end of the tutorial	3.7 GB

The download takes another 748 MB until you delete it after Step 4. While Step 2 runs, the download and the suite together take 3.4 GB, less than the total. To see the free space in your home directory, run:

$ df -h ~

Basic Verilog and basic terminal use. You will save text files and run commands.
git, make and GNU awk, which Chapters 5 to 8 need. Install them now:

$ sudo apt update
$ sudo apt install -y git make gawk

GNU awk is required because Ubuntu's default awk is mawk, which lacks the gensub function that the riscv-formal summary script calls. Chapter 7 shows the resulting error.

Why not install with apt or build from source?

The command sudo apt install yosys installs an older Yosys, and no Ubuntu release packages sby. The table compares the distribution packages with the suite release this tutorial uses.

Source	Yosys version	Yosys release date	sby
Ubuntu 22.04 (apt)	0.9	August 2019	Not packaged
Ubuntu 24.04 (apt)	0.33	September 2023	Not packaged
Ubuntu 26.04 (apt)	0.52	April 2025	Not packaged
OSS CAD Suite 2026-10-22	0.70+190	October 2026	v0.70-9-g79fc9ed

Yosys publishes a release about once a month: eighteen releases separate Ubuntu 26.04's 0.52 from the suite's 0.70. A distribution Yosys combined with a separately installed sby is a combination that no one has tested together.

Building from source requires building Yosys, sby and every solver separately. The official SymbiYosys installation guide gives build steps for Yosys, sby, Boolector and Yices 2 and refers to each project for the others. Its package list is written for Ubuntu 20.04, and it recommends Boolector, whose repository is archived and names Bitwuzla as its successor.

The OSS CAD Suite avoids both problems. YosysHQ builds Yosys, sby, the solvers, the waveform viewers and the simulators every night from their current source code and publishes them as one dated release. On Linux x86-64 it requires no other system packages.

Step 1. Download the pinned release

Releases are named by date at github.com/YosysHQ/oss-cad-suite-build/releases. Install the 2026-10-22 release, so that your output matches the output on these pages:

$ cd ~
$ curl -LO https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-10-22/oss-cad-suite-linux-x64-20261022.tgz

The -L option is required. GitHub answers the request with a redirect, and without -L curl saves the redirect's empty response instead of the archive. The release publishes no checksums, so confirm the download by its exact size:

$ stat -c %s oss-cad-suite-linux-x64-20261022.tgz

output

748265110

The size must be 748,265,110 bytes. If it differs, delete the file and download it again.

Step 2. Extract the archive

$ mkdir -p ~/tools
$ tar -xzf oss-cad-suite-linux-x64-20261022.tgz -C ~/tools
$ ls -1 ~/tools/oss-cad-suite

output

README
VERSION
bin
environment
environment.fish
etc
examples
include
lib
libexec
license
py3bin
share
super_prove

The suite now occupies ~/tools/oss-cad-suite. After Step 4 confirms that it works, delete the archive:

$ rm ~/oss-cad-suite-linux-x64-20261022.tgz

Step 3. Activate the suite

The tools are not yet on your PATH. Activate the suite:

$ source ~/tools/oss-cad-suite/environment

The prompt now starts with ⦗OSS CAD Suite⦘. Activation works like a Python virtual environment: it puts the suite's bin and py3bin folders first on your PATH, so python3 and pip3 become the suite's Python 3.11.6. It lasts until you close the terminal or run deactivate, so run the source command in every new terminal.

This tutorial uses activation for two reasons. The commands and output on every page assume it. And it changes nothing outside the current terminal: your shell configuration and your system python3 stay as they are.

Step 4. Check the installed versions

These commands print where yosys and sby come from and the version of each tool. The output below lists the versions this tutorial uses.

$ which yosys sby | sed "s#$HOME#~#"
$ yosys -V
$ sby --version
$ for t in yices-smt2 z3 bitwuzla boolector rIC3; do $t --version | head -1; done

output

~/tools/oss-cad-suite/bin/yosys
~/tools/oss-cad-suite/bin/sby
Yosys 0.70+190 (git sha1 485b63564, Release, Clang /usr/bin/clang++ 21.1.8)
SBY v0.70-9-g79fc9ed
Yices 2.7.0
Z3 version 4.15.5 - 64 bit
0.9.1
3.2.4
rIC3 1.5.2

The last five lines are Yices, Z3, Bitwuzla, Boolector and rIC3. Two results mean something is wrong:

If the first line is /usr/bin/yosys, a Yosys installed with apt answers instead of the suite. Remove it with sudo apt remove yosys, or put the suite first on your PATH.
If you see sby: command not found, the suite is not active in this terminal. Repeat Step 3.

Step 5. Check that GTKWave starts

A failed proof leaves a waveform of the failure, and Chapter 3, Run 2 opens one in GTKWave. Confirm that it starts:

$ gtkwave --version

output (first lines)

WARNING: Glycin running without sandbox.
GTKWave Analyzer v4.0.0-prealpha (f6d60e0) (w)1999-2022 BSI

The warning does not affect GTKWave. GTKWave opens a window, so it needs a desktop session. Over SSH without a display, it prints Could not initialize GTK! Is DISPLAY env var/xhost set?;Chapter 10, “How do you view or replay a trace?” shows how to read a trace without a viewer.

How do you update or remove the suite?

Update: download a newer release, extract it into a new folder, and point your source command or PATH line at it. Keep the old folder until your proofs pass with the new one.
Pin one release per project or course: everyone then has the same tools and gets the same output.
Remove: run rm -rf ~/tools/oss-cad-suite, and delete the PATH line from ~/.bashrc if you added it. The suite installs nothing else.

How do you fix install errors?

Message	Cause	Fix
`gzip: stdin: unexpected end of file`	The download is empty because `curl` ran without `-L`.	Download again with `curl -LO` and check the size (748,265,110 bytes).
`You must source this script`	The activation script was run instead of sourced.	`source ~/tools/oss-cad-suite/environment`
`sby: command not found`	The suite is not active in this terminal.	Repeat Step 3.
`which yosys` prints `/usr/bin/yosys`	An `apt` Yosys comes earlier on the `PATH`.	`sudo apt remove yosys`, or put the suite first.
Python packages are missing after activation	Activation switched `python3` to the suite's Python 3.11.6.	Run `deactivate`, or add the tools to your `PATH` instead (Step 3).
version `GLIBC_2.43' not found	Surfer in this release needs the Ubuntu 26.04 C library.	Use GTKWave.
`Could not initialize GTK!`	GTKWave has no desktop session.	Run it on the desktop, or read the trace as Chapter 10, “How do you view or replay a trace?” shows.