Installation

Learn how to install PySHDL, the Python library for working with SHDL circuits.

SHDL vs PySHDL

SHDL is the language for describing circuits. PySHDL is the Python library that parses, compiles, and simulates those circuits.

Requirements

• Python 3.13 or higher
• pip (Python package manager)
• A C compiler (clang recommended) for circuit simulation

Install via pip

The easiest way to install PySHDL is using pip:

pip install PySHDL

Install from source

You can also install PySHDL directly from the source:

git clone https://github.com/rafa-rrayes/SHDL.git
cd SHDL
pip install -e .

Using uv (recommended)

If you use uv for Python package management:

uv add PySHDL

What PySHDL Provides

Once installed, PySHDL gives you:

Command Line Tool

# Compile an SHDL file to C
shdlc compile myCircuit.shdl

# Compile and run
shdlc run myCircuit.shdl

Python API

from SHDL import Circuit

# Load and simulate a circuit
with Circuit("adder16.shdl") as circuit:
    circuit["A"] = 42
    circuit["B"] = 17
    circuit.step()
    print(circuit["Sum"])  # 59

Core Modules

Module	Purpose
shdl.flattener	Convert Expanded SHDL → Base SHDL
shdl.compiler	Compile Base SHDL → C code
shdl.driver	Python interface for circuit simulation
shdl.debugger	Debug info parsing and symbol management

Verify Installation

After installation, verify that PySHDL is working:

shdlc --help

Or in Python:

import shdl
print(shdl.__version__)

Next Steps

Now that you have PySHDL installed, let's build your first circuit!