Registry / testing / cocotb

cocotb

JSON →
library2.0.1pypypi✓ verified 89d ago

cocotb is a coroutine-based cosimulation library that enables writing Verilog and VHDL testbenches in Python. It provides a robust framework for verifying hardware designs by interacting directly with commercial and open-source HDL simulators. The current version is 2.0.1, with major releases typically aligning with significant architectural changes, moving towards more Pythonic async/await patterns.

pip install cocotb
INSTALL
IMPORT
SIG · COCOTB
C
cocotb
testingpythonv2.0.1
Install
1.9s avg
Import
260ms
Disk
31MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v2.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
build_error
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 1.9s · import 0.260s · 34MB
31MB installed
● package 31MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

test
✓ import cocotb
The @cocotb.test() decorator is the primary entry point for tests.
Timer
✓ from cocotb.triggers import Timer
Clock
✓ from cocotb.clock import Clock
TestFactory
✓ from cocotb.regression import TestFactory
✗ from cocotb.test import TestFactory
The TestFactory class was moved to cocotb.regression in cocotb 2.0.0.

This Python code defines a basic `cocotb` test for a D flip-flop (DFF) with clock and data inputs (`clk`, `i`) and a data output (`q`). To run this, you need a corresponding Verilog/VHDL DFF design file (e.g., `dff.v` or `dff.vhdl`) and a `Makefile` to integrate with an HDL simulator (like Icarus Verilog or GHDL). The `Makefile` typically specifies `TOPLEVEL`, `TOPLEVEL_LANG`, and `SIM` variables, and orchestrates the simulation. For simpler execution, `pytest-cocotb` can also be used.

import cocotb from cocotb.triggers import Timer, RisingEdge from cocotb.clock import Clock import os @cocotb.test() async def my_first_test(dut): """Attempt to verify D flip-flop functionality""" cocotb.log.info("Starting my_first_test") # Access signals on the DUT (Design Under Test) # These signal names (clk, i, q) correspond to ports in an HDL design clk = dut.clk i = dut.i q = dut.q # Set initial values i.value = 0 await Timer(1, units="ns") # Create a clock clock = Clock(clk, 10, units="ns") # 10 ns period, 100MHz cocotb.start_soon(clock.start()) # Assert reset if available (common in DFF designs) if hasattr(dut, 'reset_n'): # Check if 'reset_n' signal exists on DUT dut.reset_n.value = 0 await RisingEdge(clk) await RisingEdge(clk) # Ensure reset holds for a bit dut.reset_n.value = 1 await RisingEdge(clk) else: await RisingEdge(clk) # Just advance clock if no reset # Test case 1: input 0, expect output 0 (after clock edge) i.value = 0 await RisingEdge(clk) cocotb.log.info(f"Input: {i.value}, Output: {q.value}") assert q.value == 0, f"Expected q=0, got {q.value}" # Test case 2: input 1, expect output 0 (output lags input by one clock cycle) i.value = 1 await RisingEdge(clk) cocotb.log.info(f"Input: {i.value}, Output: {q.value}") assert q.value == 0, f"Expected q=0, got {q.value}" # Test case 3: input 1, expect output 1 (on the next clock edge) await RisingEdge(clk) cocotb.log.info(f"Input: {i.value}, Output: {q.value}") assert q.value == 1, f"Expected q=1, got {q.value}" cocotb.log.info("Test finished")
Debug
Known issues
breakingcocotb 2.0 introduced significant breaking changes, migrating towards native Python `async`/`await` syntax. The `@cocotb.coroutine` decorator was removed (use `async def` with `@cocotb.test()`), `cocotb.test.TestFactory` moved to `cocotb.regression.TestFactory`, and `cocotb.result` module was removed.
fix
Update test functions to `async def` and use `@cocotb.test()`. For parameterized tests, import `TestFactory` from `cocotb.regression`. Review cocotb 2.0 migration guides for full details.
affects: >=2.0.0
gotchacocotb itself is a Python library, but it requires an external HDL simulator (e.g., Icarus Verilog, GHDL, QuestaSim, VCS) to run any tests. This simulator must be installed and accessible in your system's PATH.
fix
Install a compatible HDL simulator for your target HDL (Verilog or VHDL) and ensure its executable is in your system's PATH environment variable.
affects: all
gotchaRunning `cocotb` tests typically relies on a `Makefile` to configure the simulation environment (e.g., `TOPLEVEL`, `TOPLEVEL_LANG`, `SIM`, `VERILOG_SOURCES`/`VHDL_SOURCES`, `PYTHONPATH`) and invoke the simulator. Incorrect `Makefile` configuration is a common source of issues.
fix
Carefully review the `cocotb` documentation on `Makefile` setup. Ensure `TOPLEVEL` matches your HDL top module, `TOPLEVEL_LANG` is correct, `SIM` points to an installed simulator, and `PYTHONPATH` includes the directory containing your Python test files.
affects: all
gotchaAll `cocotb` triggers (e.g., `Timer`, `RisingEdge`) and asynchronous cocotb functions must be `await`ed within an `async` test function. Forgetting `await` will not pause the simulation and can lead to unexpected behavior or tests that complete instantly.
fix
Ensure all calls to `cocotb` triggers or other `async` functions are preceded by the `await` keyword. If using an older `cocotb` version, ensure `yield` is used for `@cocotb.coroutine` functions.
affects: >=2.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cocotb'
The Python environment running the test does not have `cocotb` installed or the `PYTHONPATH` is not correctly configured to find the test modules.
fix
Run `pip install cocotb` in your active Python environment. If using a `Makefile`, ensure `PYTHONPATH` is correctly set to include the directory containing your Python test file(s).
ERROR: No tests discovered
The `cocotb` test runner could not find any functions decorated with `@cocotb.test()` in the specified test modules, or the Python test modules were not correctly loaded.
fix
Ensure your test functions are decorated with `@cocotb.test()`. Verify the `Makefile`'s `MODULE` variable points to the correct Python module (e.g., `MODULE=test_my_design`) and `PYTHONPATH` includes the directory containing `test_my_design.py`.
ERROR: [simulator] command not found
The HDL simulator specified in the `SIM` variable of your `Makefile` (e.g., `ghdl`, `iverilog`, `vsim`) is not installed or not accessible in your system's PATH.
fix
Install the required HDL simulator (e.g., Icarus Verilog for Verilog, GHDL for VHDL). Ensure its executable is added to your system's PATH environment variable.
AttributeError: module 'cocotb.test' has no attribute 'TestFactory'
You are attempting to import `TestFactory` from `cocotb.test` in `cocotb` version 2.0.0 or later.
fix
Change your import statement from `from cocotb.test import TestFactory` to `from cocotb.regression import TestFactory`.
Upgrade
Version history
2.0.1latest on PyPI · released Nov 15, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
53 hits · last 30 days
node
49
OpenAI (training)
1
Resources
cocotb — pip install cocotb · libregistry