Release Notes

All releases are available from the GitHub Releases Page.

cocotb 1.5.0.dev0 (2020-10-20)


  • Makefiles now automatically deduce TOPLEVEL_LANG based on the value of VERILOG_SOURCES and VHDL_SOURCES. Makefiles also detect incorrect usage of TOPLEVEL_LANG for simulators that only support one language. (#1982)

  • cocotb.fork() will now raise a descriptive TypeError if a coroutine function is passed into them. (#2006)

  • Added cocotb.scheduler.start_soon() which schedules a coroutine to start after the current coroutine yields control. This behavior is distinct from cocotb.fork() which schedules the given coroutine immediately. (#2023)


  • Fix GHDL’s library search path, allowing libraries other than work to be used in simulation. (#2038)

  • Tests skipped by default (created with skip=True) can again be run manually by setting the TESTCASE variable. (#2045)

  • Generate blocks are now accessible directly via lookup without having to iterate over parent handle. (#2079)

    # Example pseudo-region
    dut.genblk1       #<class 'cocotb.handle.HierarchyArrayObject'>
  • Fixed an issue with VHPI on Mac OS and Linux where negative integers were returned as large positive values. (#2129)

Improved Documentation

Deprecations and Removals


Cocotb 1.4.0 (2020-07-08)


  • Lock can now be used in async with statements. (#1031)

  • Add support for distinguishing between NET (vpiNet) and REG (vpiReg) type when using vpi interface. (#1107)

  • Support for dropping into pdb upon failure, via the new COCOTB_PDB_ON_EXCEPTION environment variable (#1180)

  • Simulators run through a TCL script (Aldec Riviera Pro and Mentor simulators) now support a new RUN_ARGS Makefile variable, which is passed to the first invocation of the tool during runtime. (#1244)

  • Cocotb now supports the following example of forking a non-decorated async coroutine.

    async def example():
        for i in range(10):
            await cocotb.triggers.Timer(10, "ns")

    Issue (#1255)

  • The cocotb log configuration is now less intrusive, and only configures the root logger instance, logging.getLogger(), as part of cocotb.log.default_config() (#1266).

    As such, it is now possible to override the default cocotb logging behavior with something like:

    # remove the cocotb log handler and formatting
    root = logging.getLogger()
    for h in root.handlers[:]:
    # add your own
  • Support for vpiRealNet (#1282)

  • The colored output can now be disabled by the NO_COLOR environment variable. (#1309)

  • Cocotb now supports deposit/force/release/freeze actions on simulator handles, exposing functionality similar to the respective Verilog/VHDL assignments.

    from cocotb.handle import Deposit, Force, Release, Freeze
    dut.q <= 1            # A regular value deposit
    dut.q <= Deposit(1)   # The same, higher verbosity
    dut.q <= Force(1)     # Force value of q to 1
    dut.q <= Release()    # Release q from a Force
    dut.q <= Freeze()     # Freeze the current value of q

    Issue (#1403)

  • Custom logging handlers can now access the simulator time using logging.LogRecord.created_sim_time, provided the SimTimeContextFilter filter added by default_config() is not removed from the logger instance. (#1411)

  • Questa now supports PLUSARGS. This requires that tcl.h be present on the system. This is likely included in your installation of Questa, otherwise, specify CFLAGS=-I/path/to/tcl/includedir. (#1424)

  • The name of the entry point symbol for libraries in GPI_EXTRA can now be customized. The delimiter between each library in the list has changed from : to ,. (#1457)

  • New methods for setting the value of a NonHierarchyIndexableObject (HDL arrays). (#1507)

    # Now supported
    dut.some_array <= [0xAA, 0xBB, 0xCC]
    dut.some_array.value = [0xAA, 0xBB, 0xCC]
    # For simulators that support n-dimensional arrays
    dut.some_2d_array <= [[0xAA, 0xBB], [0xCC, 0xDD]]
    dut.some_2d_array.value = [[0xAA, 0xBB], [0xCC, 0xDD]]
  • Added support for Aldec’s Active-HDL simulator. (#1601)

  • Including from user makefiles is now a no-op and deprecated. Lines like include $(shell cocotb-config --makefiles)/ can be removed from user makefiles without loss in functionality. (#1629)

  • Support for using await inside an embedded IPython terminal, using cocotb.ipython_support. (#1649)

  • Added is_set(), so users may check if an Event has fired. (#1723)

  • The cocotb.simulator.is_running() function was added so a user of cocotb could determine if they are running within a simulator. (#1843)


  • Tests which fail at initialization, for instance due to no yield being present, are no longer silently ignored (#1253)

  • Tests that were not run because predecessors threw cocotb.result.SimFailure, and caused the simulator to exit, are now recorded with an outcome of cocotb.result.SimFailure. Previously, these tests were ignored. (#1279)

  • Makefiles now correctly fail if the simulation crashes before a results.xml file can be written. (#1314)

  • Logging of non-string messages with colored log output is now working. (#1410)

  • Getting and setting the value of a NonHierarchyIndexableObject now iterates through the correct range of the simulation object, so arrays that do not start/end at index 0 are supported. (#1507)

  • The XGMII monitor no longer crashes on Python 3, and now assembles packets as bytes instead of str. The XGMII driver has expected bytes since cocotb 1.2.0. (#1545)

  • signal <= value_of_wrong_type no longer breaks the scheduler, and throws an error immediately. (#1661)

  • Scheduling behavior is now consistent before and after the first await of a GPITrigger. (#1705)

  • Iterating over for generate statements using VHPI has been fixed. This bug caused some simulators to crash, and was a regression in version 1.3. (#1882)

  • The XGMII driver no longer emits a corrupted word on the first transfer. (#1905)

Improved Documentation

  • If a makefile uses cocotb’s Makefile.sim, make help now lists the supported targets and variables. (#1318)

  • A new section Rotating Log Files has been added. (#1400)

  • The documentation at has been restructured, making it easier to find relevant information. (#1482)

Deprecations and Removals

  • cocotb.utils.reject_remaining_kwargs() is deprecated, as it is no longer needed now that we only support Python 3.5 and newer. (#1339)

  • The value of cocotb.handle.StringObjects is now of type bytes, instead of str with an implied ASCII encoding scheme. (#1381)

  • ReturnValue is now deprecated. Use a return statement instead; this works in all supported versions of Python. (#1489)

  • The makefile variable VERILATOR_TRACE that was not supported for all simulators has been deprecated. Using it prints a deprecation warning and points to the documentation section Simulator Support explaining how to get the same effect by other means. (#1495)

  • BinaryValue.get_hex_buff produced nonsense and has been removed. (#1511)

  • Passing str instances to cocotb.utils.hexdump() and cocotb.utils.hexdiffs() is deprecated. bytes objects should be passed instead. (#1519)

  • Makefile.pylib, which provided helpers for building C extension modules for Python, has been removed. Users of the PYTHON_LIBDIR and PYTHON_INCLUDEDIR variables will now have to compute these values themselves. See the endian_swapper example for how to do this. (#1632)

  • Makefile and documentation for the NVC simulator which has never worked have been removed. (#1693)


  • Cocotb no longer supports Python 2, at least Python 3.5 is now required. Users of Python 2.7 can still use cocotb 1.3, but are heavily encouraged to update. It is recommended to use the latest release of Python 3 for improved performance over older Python 3 versions. (#767)

  • Mentor Questa, Aldec Riviera-PRO and GHDL are now started in the directory containing the Makefile and also save results.xml there, bringing them in line with the behavior used by other simulators. (#1598) (#1599) (#1063)

  • Tests are now evaluated in order of their appearance in the MODULE environment variable, their stage, and the order of invocation of the cocotb.test decorator within a module. (#1380)

  • All libraries are compiled during installation to the cocotb/libs directory. The interface libraries libcocotbvpi and libcocotbvhpi have been renamed to have a _simulator_name postfix. The simulator module has moved to cocotb.simulator. The LD_LIBRARY_PATH environment variable no longer needs to be set by the makefiles, as the libraries now discover each other via RPATH settings. (#1425)

  • Cocotb must now be installed before it can be used. (#1445)

  • cocotb.handle.NonHierarchyIndexableObject.value is now a list in left-to-right range order of the underlying simulation object. Previously the list was always ordered low-to-high. (#1507)

  • Various binary representations have changed type from str to bytes. These include:

    Code working with these objects may find it needs to switch from creating str objects like "this" to bytes objects like b"this". This change is a consequence of the move to Python 3. (#1514)

  • There’s no longer any need to set the PYTHON_BIN makefile variable, the Python executable automatically matches the one cocotb was installed into. (#1574)

  • The SIM setting for Aldec Riviera-PRO has changed from aldec to riviera. (#1691)

  • Certain methods on the cocotb.simulator Python module now throw a RuntimeError when no simulator is present, making it safe to use cocotb without a simulator present. (#1843)

  • Invalid values of the environment variable COCOTB_LOG_LEVEL are no longer ignored. They now raise an exception with instructions how to fix the problem. (#1898)

cocotb 1.3.2

Released on 08 July 2020

Notable changes and bug fixes

  • Iterating over for generate statements using VHPI has been fixed. This bug caused some simulators to crash, and was a regression in version 1.3.1. (#1882)

cocotb 1.3.1

Released on 15 March 2020

Notable changes and bug fixes

  • The Makefiles for the Aldec Riviera and Cadence Incisive simulators have been fixed to use the correct name of the VHPI library (libcocotbvhpi). This bug prevented VHDL designs from being simulated, and was a regression in 1.3.0. (#1472)

cocotb 1.3.0

Released on 08 January 2020

This will likely be the last release to support Python 2.7.

New features

Notable changes and bug fixes

  • DeprecationWarnings are now shown in the output by default.

  • Tracebacks are now preserved correctly for exceptions in Python 2. The tracebacks in all Python versions are now a little shorter.

  • cocotb.external() and cocotb.function() now work more reliably and with fewer race conditions.

  • A failing assert will be considered a test failure. Previously, it was considered a test error.

  • drivers() and loads() now also work correctly in Python 3.7 onwards.

  • cocotb.triggers.Timer can now be used with decimal.Decimal instances, allowing constructs like Timer(Decimal('1e-9'), units='sec') as an alternate spelling for Timer(100, units='us'). (#1114)

  • Many (editorial) documentation improvements.


  • cocotb.result.raise_error and cocotb.result.create_error are deprecated in favor of using Python exceptions directly. TestError can still be used if the same exception type is desired. (#1109)

  • The AvalonSTPktsWithChannel type is deprecated. Use the report_channel argument to AvalonSTPkts instead.

  • The colour attribute of log objects like cocotb.log or some_coro.log is deprecated. Use cocotb.utils.want_color_output() instead. (#1231)

Other news

cocotb 1.2.0

Released on 24 July 2019

New features

  • cocotb is now built as Python package and installable through pip. (#517, #799, #800, #803, #805)

  • Support for async functions and generators was added (Python 3 only). Please have a look at Coroutines for an example how to use this new feature.

  • VHDL block statements can be traversed. (#850)

  • Support for Python 3.7 was added.

Notable changes and bug fixes

  • The heart of cocotb, its scheduler, is now even more robust. Many small bugs, inconsistencies and unreliable behavior have been ironed out.

  • Exceptions are now correctly propagated between coroutines, giving users the “natural” behavior they’d expect with exceptions. (#633)

  • The setimmediatevalue() function now works for values larger than 32 bit. (#768)

  • The documentation was cleaned up, improved and extended in various places, making it more consistent and complete.

  • Tab completion in newer versions of IPython is fixed. (#825)

  • Python 2.6 is officially not supported any more. cocotb supports Python 2.7 and Python 3.5+.

  • The cocotb GitHub project moved from potentialventures/cocotb to cocotb/cocotb. Redirects for old URLs are in place.


  • The bits argument to BinaryValue, which is now called n_bits.

  • The logger attribute of log objects like cocotb.log or some_coro.log, which is now just an alias for self.

  • The cocotb.utils.get_python_integer_types function, which was intended to be private.

Known issues

  • Depending on your simulation, cocotb 1.2 might be roughly 20 percent slower than cocotb 1.1. Much of the work in this release cycle went into fixing correctness bugs in the scheduler, sometimes at the cost of performance. We are continuing to investigate this in issue #961. Independent of the cocotb version, we recommend using the latest Python 3 version, which is shown to be significantly faster than previous Python 3 versions, and slightly faster than Python 2.7.

Please have a look at the issue tracker for more outstanding issues and contribution opportunities.

cocotb 1.1

Released on 24 January 2019.

This release is the result of four years of work with too many bug fixes, improvements and refactorings to name them all. Please have a look at the release announcement on the mailing list for further information.

cocotb 1.0

Released on 15 February 2015.

New features

  • FLI support for ModelSim

  • Mixed Language, Verilog and VHDL

  • Windows

  • 300% performance improvement with VHPI interface

  • WaveDrom support for wave diagrams.

cocotb 0.4

Released on 25 February 2014.

New features

  • Issue #101: Implement Lock primitive to support mutex

  • Issue #105: Compatibility with Aldec Riviera-Pro

  • Issue #109: Combine multiple results.xml into a single results file

  • Issue #111: XGMII drivers and monitors added

  • Issue #113: Add operators to BinaryValue class

  • Issue #116: Native VHDL support by implementing VHPI layer

  • Issue #117: Added AXI4-Lite Master BFM

Bugs fixed

  • Issue #100: Functional bug in endian_swapper example RTL

  • Issue #102: Only 1 coroutine wakes up of multiple coroutines wait() on an Event

  • Issue #114: Fix build issues with Cadence IUS simulator

New examples

  • Issue #106: TUN/TAP example using ping

cocotb 0.3

Released on 27 September 2013.

This contains a raft of fixes and feature enhancements.

cocotb 0.2

Released on 19 July 2013.

New features

  • Release 0.2 supports more simulators and increases robustness over 0.1.

  • A centralized installation is now supported (see documentation) with supporting libraries build when the simulation is run for the first time.

cocotb 0.1

Released on 9 July 2013.

  • The first release of cocotb.

  • Allows installation and running against Icarus, VCS, Aldec simulators.