Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

cocotb is a coroutine based cosimulation library for writing VHDL and Verilog testbenches in Python.

Documentation Status Build Status PyPI Gitpod Ready-to-Code codecov


Cocotb requires:

After installing these dependencies, the latest stable version of cocotb can be installed with pip.

pip install cocotb

!!! Windows Users !!! See here for installation instructions.

For more details on installation, including prerequisites, see the documentation.

For detail on how to install the development version of cocotb, see the lastest documentation.


As a first trivial introduction to cocotb, the following example "tests" a flip-flop.

First, we need a hardware design which we can test. For this example, create a file with SystemVerilog code for a simple D flip-flop. You could also use any other language a cocotb-supported simulator understands, e.g. VHDL.


`timescale 1us/1ns

module dff (
    output logic q,
    input logic clk, d

always @(posedge clk) begin
    q <= d;


An example of a simple randomized cocotb testbench:


import random
import cocotb
from cocotb.clock import Clock
from cocotb.triggers import FallingEdge

async def test_dff_simple(dut):
    """ Test that d propagates to q """

    clock = Clock(dut.clk, 10, units="us")  # Create a 10us period clock on port clk
    cocotb.fork(clock.start())  # Start the clock

    for i in range(10):
        val = random.randint(0, 1)
        dut.d <= val  # Assign the random value val to the input port d
        await FallingEdge(dut.clk)
        assert dut.q == val, "output q was incorrect on the {}th cycle".format(i)

A simple Makefile:

# Makefile

VERILOG_SOURCES = $(shell pwd)/
MODULE = test_dff

include $(shell cocotb-config --makefiles)/Makefile.sim

In order to run the test with Icarus Verilog, execute:

make SIM=icarus


For more information please see the cocotb documentation and the wiki.

Tutorials, examples and related projects

For more related resources please check the wiki and the list of projects depending on cocotb.

You can’t perform that action at this time.