Convert SystemVerilog modules into readable logic-diagram SVGs with a single CLI command. sv2svg parses structural HDL, places gates left-to-right, and outputs Schemdraw-based graphics that stay aligned and symmetric.
- Deterministic left-to-right layout with minimal crossings
- Automatic input ordering (alphabetical, module ports, or auto)
- Optional grid snapping and symmetry controls
- Visual enhancements: gate fill colors, line styling, fan-out indicators, 6 style presets
- Full expression parser: supports complex boolean expressions with operator precedence
- Truth table generation: automatic verification for circuits ≤5 inputs
- CLI-first workflow with
--help,--version,--style, and--orientationdiscovery - Semantic-release driven SemVer tagging and automated PyPI publishing
Choose one of the following approaches:
- uvx (no install):
uvx sv2svg --help
- uv run:
uv run sv2svg --help
- Virtual environment:
python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install sv2svg - Editable checkout:
python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -e .
sv2svg --help
sv2svg --version
# Basic usage
sv2svg input.sv -o output.svg
# With visual enhancements
sv2svg input.sv --fill-gates --signal-styles --style vibrant -o output.svg
# Full-featured diagram with truth table
sv2svg input.sv --fill-gates --signal-styles --fanout-wires --table --style vibrant -o output.svg
# Vertical layout with dark theme
sv2svg input.sv --orientation vertical --style dark -o output.svgusage: sv2svg [-h] [-o OUTPUT] [--input-order {alpha,ports,auto}]
[--grid-x GRID_X] [--grid-y GRID_Y] [--no-symmetry]
[--style {classic,blueprint,midnight,mono,vibrant,dark}]
[--orientation {horizontal,vertical}] [--table] [--no-caption]
[--fill-gates] [--signal-styles] [--fanout-wires] [-V]
input_file
input_file— source SystemVerilog file with the module to visualize-o / --output— target SVG file path (-writes SVG to stdout)-V / --version— print the sv2svg version derived from git metadata
--input-order {alpha,ports,auto}— sort inputs alphabetically, preserve declaration order, or auto-detect (default:alpha)--grid-x GRID_X— snap X coordinates to grid (default: 0, disabled by default)--grid-y GRID_Y— snap Y coordinates to grid (default: 0, disabled by default)--no-symmetry— disable mirrored placement for sibling signals around shared drivers--orientation {horizontal,vertical}— layout direction: left-to-right or top-to-bottom (default:horizontal)
--style {classic,blueprint,midnight,mono,vibrant,dark}— color/line-weight preset (default:classic)classic— Dark blue-gray with subtle stylingblueprint— NASA blue for technical documentationmidnight— Cyan on dark backgroundmono— Grayscale for print-friendly outputvibrant— Bright gate colors (best with--fill-gates)dark— Light-on-dark theme for dark mode documentation
--fill-gates— Add subtle fill colors to logic gates for visual distinction--signal-styles— Use line styles to distinguish signal types (solid=primary I/O, dashed=intermediate)--fanout-wires— Use thicker lines for signals driving multiple gates (visual fan-out indicator)--table— Include truth table in diagram (only for circuits with ≤5 inputs)--no-caption— Suppress "Module: modulename" caption for cleaner diagrams--no-internal-labels— Suppress labels on auto-generated elements (auto_, expr)--no-labels— Suppress ALL labels except inputs and outputs--font-scale FLOAT— Font size scale factor (default: 1.2 for slightly larger fonts)
- Keep each module in its own file and ensure port declarations are explicit.
- The parser expects synthesizable structural constructs; unsupported statements raise errors during generation.
- Use the grid options to align gates when mixing manual annotations with generated drawings.
sv2svg is designed for structural SystemVerilog and supports both explicit gate instantiations and complex boolean expressions in assign statements.
module example(a, b, y);
input logic a, b;
output logic y;
logic ab;
AND u1(a, b, ab);
NOT u2(ab, y);
endmoduleSupported gate types: AND, OR, NAND, NOR, XOR, XNOR, NOT/INV, BUF/BUFFER
The full expression parser handles complex boolean expressions with proper operator precedence and parentheses:
// Simple expressions
assign y = a & b; // AND gate
assign y = a | b; // OR gate
assign y = ~a; // NOT gate
// Operator precedence (NOT > AND > OR/XOR)
assign y = a | b & c; // OR(a, AND(b,c))
assign y = ~a & b | c; // OR(AND(NOT(a),b), c)
// Parentheses override precedence
assign y = (a | b) & c; // AND(OR(a,b), c)
assign y = ~(a & b | c); // NOT(OR(AND(a,b), c))
// Multi-input expressions (cascaded gates)
assign y = a & b & c; // AND(AND(a,b), c) with auto-generated intermediate signal
assign y = a | b | c | d; // Cascaded OR gates
// Complex nested expressions
assign y = (a & b) | (c & d); // OR(AND(a,b), AND(c,d))
assign y = ~((a | b) & c); // NOT(AND(OR(a,b), c))
// Timing delays (displayed as 't:N' label inside gate)
assign #3 y = a & b; // AND gate with 3-unit delayThe parser automatically:
- Generates intermediate signals for complex expressions (
_expr_1,_expr_2, etc.) - Applies correct operator precedence
- Handles nested parentheses
- Creates cascaded gates for multi-input operations
The parser cannot handle:
- Ternary operators:
assign y = sel ? a : b; - Bit operations:
assign y = a[0] & b[1]; - Arithmetic:
assign y = a + b; - Comparison operators:
assign y = a > b;
For these constructs, use explicit gate instantiations or different HDL representations.
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
python -m sv2svg.cli --versionRun the CLI against fixtures or your own modules; any Python exception surfaces with a clear message.
The CI workflow (.github/workflows/ci.yml) installs the package in editable mode and performs an import smoke test. Extend it with richer checks as the project grows.
- Commits merged to
mainmust follow Conventional Commits so semantic-release can infer version bumps. - On qualifying commits, the Release workflow updates
CHANGELOG.md, tags the release, publishes GitHub release notes, and uploads the built artifacts to PyPI using trusted publishing. - Local builds without git metadata fall back to version
0.0.0; regular development builds look like0.2.1.dev0+g8733005aa.d20250922courtesy of hatch-vcs.
Issues and pull requests are welcome. Please include reproduction snippets for parser bugs and respect the release automation by using Conventional Commit messages.
MIT