Complete guide to using Yosys show command to export RTL and gate-level schematics — with all options, real examples, and netlistsvg alternative.
TL;DR — Export schematic as SVG in one command:
yosys -p "read_verilog design.v; synth -top top_module; show -format svg -prefix schematic"
Produces schematic.svg in the current directory. Requires Graphviz installed.
The Yosys show command renders the current design's netlist as a graph using Graphviz's dot layout engine. It visualizes:
Prerequisite: Graphviz must be installed and dot must be in your PATH. Test with dot -V. Install: Ubuntu: sudo apt install graphviz | macOS: brew install graphviz | Windows: graphviz.org/download
-format <fmt>Output format: svg, pdf, png, ps, dot, json. Default: dot (launches viewer)
-prefix <name>Output filename prefix. With -format svg, creates <name>.svg
-viewer <cmd>Launch viewer after rendering. e.g. -viewer xdg-open or -viewer eog
-module <mod>Show specific module only. Without it, shows top module
-colors <N>Assign N random colors to distinguish nets/cells
-stretchStretch the schematic for better readability of wide designs
-widthAdjust output width for landscape rendering
-notitleSuppress the module name title from the output
-nobgDon't launch in background — wait for viewer to close
-pausePause Yosys until the viewer window is closed
-dpi <N>DPI for PNG output. Default: 72. Use 150-300 for print quality
-enumEnumerate cells — add numbers to help identify them
# Visualize RTL before synthesis read_verilog counter.v hierarchy -top counter proc # convert always blocks to logic show -format svg -prefix counter_rtl
# Synthesize then visualize gate-level netlist
read_verilog fsm.v
synth -top fsm -flatten
show -format svg -prefix fsm_gates -stretch
# Quick SVG generation from terminal yosys -p "read_verilog alu.v; synth -top alu; show -format svg -prefix alu_schematic" # With specific module (useful in multi-module designs) yosys -p "read_verilog top.v; hierarchy -top top; show -format svg -prefix top_rtl -module alu_unit"
read_verilog adder.v synth -top adder show -format png -prefix adder_schema -dpi 150
# Step 1: Export as .dot file yosys -p "read_verilog design.v; synth -top top; show -format dot -prefix design" # Step 2: Convert .dot to any format with Graphviz dot -Tsvg design.dot -o design.svg dot -Tpng design.dot -o design.png -Gdpi=150 dot -Tpdf design.dot -o design.pdf
# save as synth_show.ys → run with: yosys synth_show.ys # Read design read_verilog -sv design.sv # Hierarchy check hierarchy -check -top top_module # RTL elaboration proc opt memory # Export RTL-level schematic show -format svg -prefix rtl_view -colors 3 # Technology mapping techmap opt # Export gate-level schematic show -format svg -prefix gate_view -stretch # Write netlist write_verilog netlist.v stat
netlistsvg produces cleaner, more readable schematics than Yosys show — with proper gate symbols (AND, OR, MUX, DFF icons) instead of raw Graphviz boxes.
# Step 1: Install netlistsvg npm install -g netlistsvg # Step 2: Export Yosys JSON yosys -p "read_verilog design.v; synth -top top; write_json design.json" # Step 3: Generate pretty SVG netlistsvg design.json -o schematic.svg # Open in browser xdg-open schematic.svg # Linux open schematic.svg # macOS
netlistsvg vs yosys show: netlistsvg renders with standard IEEE logic gate symbols (triangle for buffer, D-shape for AND) — much better for documentation and presentations. Yosys show uses generic box-and-wire Graphviz layout — better for debugging internal Yosys cell structure and large complex netlists.
| Format | Command | Best For | Graphviz needed? |
|---|---|---|---|
| svg | -format svg | Web, documentation, browser-viewable | Yes |
| png | -format png | Slides, reports, raster images | Yes |
-format pdf | Print-quality documentation | Yes | |
| ps | -format ps | PostScript for printing | Yes |
| dot | -format dot | Debug or manual Graphviz processing | No (outputs raw dot) |
| json | write_json (separate cmd) | netlistsvg rendering | No |
| Problem | Cause | Fix |
|---|---|---|
| ERROR: dot not found | Graphviz not installed or not in PATH | sudo apt install graphviz — verify with dot -V |
| Empty or tiny SVG | Design not elaborated — proc not run | Add proc; opt; before show |
| Wrong module shown | Top module not specified | Add -module <module_name> or run hierarchy -top top |
| SVG too large to read | Large design — too many cells | Use -module to show one submodule at a time |
| show hangs / no output | Viewer launched in foreground | Add -format svg -prefix name — don't use interactive viewer mode |
| SystemVerilog not parsed | Missing -sv flag | read_verilog -sv design.sv |
# Generate schematics as part of build
DESIGN = top_module
SRC = src/$(DESIGN).v
schematic: $(SRC)
yosys -p "read_verilog $(SRC); \
synth -top $(DESIGN); \
show -format svg -prefix docs/$(DESIGN)_schematic"
rtl_view: $(SRC)
yosys -p "read_verilog $(SRC); \
hierarchy -top $(DESIGN); proc; \
show -format svg -prefix docs/$(DESIGN)_rtl"
.PHONY: schematic rtl_view
Run: yosys -p "read_verilog design.v; synth -top top; show -format svg -prefix output". This creates output.svg. Graphviz must be installed (sudo apt install graphviz).
-prefix sets the base filename for output. With -format svg -prefix mydesign, Yosys creates mydesign.svg. Without -prefix, a temporary file is used and opened in a viewer.
Install Graphviz: Ubuntu: sudo apt install graphviz. macOS: brew install graphviz. Windows: download from graphviz.org. Verify: dot -V. Then re-run Yosys.
Export with -format svg, then open the .svg file directly in Chrome, Firefox, or Edge. SVG files are natively supported in all modern browsers — just drag and drop.
netlistsvg is a separate tool (npm install -g netlistsvg) that renders Yosys JSON netlists with IEEE gate symbols. It produces prettier, documentation-quality schematics. Yosys show uses Graphviz boxes — better for debugging internal structure. For presentations, use netlistsvg.