Simulator Support#
This page lists the simulators that cocotb can be used with and documents specifics, limitations, workarounds etc.
In general, cocotb can be used with any simulator supporting the industry-standard VPI, VHPI or FLI interfaces. However, in practice simulators exhibit small differences in behavior that cocotb mostly takes care of.
If a simulator you would like to use with cocotb is not listed on this page open an issue at the cocotb GitHub issue tracker.
Icarus Verilog#
Note
cocotb supports Icarus 11.0+.
In order to use this simulator, set SIM to icarus:
make SIM=icarus
# or
SIM=icarus [...] pytest [...]
For simulator-specific limitations when running with the Python Runner flow,
see cocotb_tools.runner.Icarus.
Note
A working installation of Icarus Verilog is required. You can find installation instructions in the Icarus Verilog Installation Guide.
Waveforms#
Icarus Verilog can produce waveform traces in the FST format. FST traces are much smaller and more efficient to write than VCD. They can be viewed with GTKWave or with Surfer.
To enable FST tracing, set WAVES to 1.
make SIM=icarus WAVES=1
By default, the wave file will be named <hdl_toplevel>.fst. Unlike other simulators, it will be placed in the build directory, rather than the test directory.
To redirect the wave file to a different location, use the plusarg dumpfile_path when running the test.
Reported Issues for this Simulator#
Verilator#
Note
cocotb supports Verilator 5.036+.
In order to use this simulator, set SIM to verilator:
make SIM=verilator
# or
SIM=verilator [...] pytest [...]
For simulator-specific limitations when running with the Python Runner flow,
see cocotb_tools.runner.Verilator.
Note
A working installation of Verilator is required. You can find installation instructions in the Verilator documentation.
Added in version 1.3.
Changed in version 1.5: Improved cocotb support and greatly improved performance when using a higher time precision.
Changed in version 2.0: Reimplemented the Verilator evaluator loop used in cocotb tests. This allowed for better performance and behavior more consistent with event-based simulators. Additionally, added support for inertial writes, which noticeably improves performance.
Coverage#
To enable HDL code coverage, add Verilator’s coverage option(s) to the EXTRA_ARGS make variable, for example:
EXTRA_ARGS += --coverage
This will result in coverage data being written to coverage.dat.
Waveforms#
To get waveforms in VCD format, add Verilator’s trace option(s) to the
EXTRA_ARGS make variable, for example in a Makefile:
EXTRA_ARGS += --trace --trace-structs
To set the same options on the command line, use EXTRA_ARGS="--trace --trace-structs" make ....
A VCD file named dump.vcd will be generated in the current directory.
Verilator can produce waveform traces in the FST format. FST traces are much smaller and more efficient to write. They can be viewed with GTKWave or with Surfer.
To enable FST tracing, add --trace-fst to EXTRA_ARGS as shown below.
EXTRA_ARGS += --trace --trace-fst --trace-structs
The resulting file will be dump.fst and can be opened by gtkwave dump.fst.
Power Estimation#
Verilator (versions 5.042 and higher) can generate SAIF activity files for use in power estimation. These compact files do not record the state of signals over time, rather they record general switching statistics to calculate the amount of power dissipated by each signal.
To enable SAIF tracing, if using the Makefiles, add --trace-saif to EXTRA_ARGS as shown below.
EXTRA_ARGS += --trace --trace-saif --trace-structs
If you are using the runner add --trace-saif to the build_args argument to Runner.build().
runner.build(
build_args=["--trace", "--trace-saif", "--trace-structs"],
)
The resulting file will be dump.saif which can be processed by most synthesis tools.
Note
For any given build, only one output format (VCD, FST, or SAIF) can be used. If both waveform tracing and activity tracing are needed, they should be done with different builds.
Reported Issues for this Simulator#
Synopsys VCS#
In order to use this simulator, set SIM to vcs:
make SIM=vcs
# or
SIM=vcs [...] pytest [...]
For simulator-specific limitations when running with the Python Runner flow,
see cocotb_tools.runner.Vcs.
Note
A working installation of the simulator itself is required.
cocotb currently only supports VPI for Synopsys VCS, not VHPI.
Reported Issues for this Simulator#
Aldec Riviera-PRO#
In order to use this simulator, set SIM to riviera:
make SIM=riviera
# or
SIM=riviera [...] pytest [...]
For simulator-specific limitations when running with the Python Runner flow,
see cocotb_tools.runner.Riviera.
Note
A working installation of the simulator itself is required.
Note
On Windows, do not install the C++ compiler, i.e. unselect it during the installation process of Riviera-PRO.
(A workaround is to remove or rename the mingw directory located in the Riviera-PRO installation directory.)
Deprecated since version 1.4: Support for Riviera-PRO was previously available with SIM=aldec.
The LICENSE_QUEUE environment variable can be used for this simulator –
this setting will be mirrored in the TCL license_queue variable to control runtime license checkouts.
Reported Issues for this Simulator#
Aldec Active-HDL#
In order to use this simulator, set SIM to activehdl:
make SIM=activehdl
This simulator is not currently supported in the Python Runner flow.
Note
A working installation of the simulator itself is required.
Warning
cocotb does not work with some versions of Active-HDL (see #1494).
Known affected versions:
Aldec Active-HDL 10.4a
Aldec Active-HDL 10.5a
Reported Issues for this Simulator#
Mentor/Siemens EDA Questa#
In order to use this simulator, set SIM to questa:
make SIM=questa
# or
SIM=questa [...] pytest [...]
For simulator-specific limitations when running with the Python Runner flow,
see cocotb_tools.runner.Questa.
Note
A working installation of the simulator itself is required.
cocotb implements two flows for Questa. The most suitable flow is chosen based on the Questa version being used.
The newer QIS/Qrun flow uses the Questa Information System (QIS) together with the qrun command.
One of the most visible user-facing benefits of the qrun flow is the ability to automatically order VHDL sources.
The use of the QIS should reduce the overhead from accessing design internals at runtime and mandates the use of Visualizer as GUI.
The QIS/Qrun flow is chosen automatically if Questa 2025.2 or newer is detected.
Users can explicitly use the QIS/Qrun flow with SIM=questa-qisqrun.
If you are passing simulator-specific arguments to the Makefile, we recommend not relying on the automatic flow selection and instead explicitly selecting a flow by using either SIM=questa-qisqrun or SIM=questa-compat to ensure they are interpreted as expected.
The compat flow uses the commands vlog, vopt and vsim to build and run the simulation, together with the +acc switch to enable design access for cocotb.
The compat flow is used for ModelSim and Questa older than 2025.2.
Users can explicitly use the compat flow with SIM=questa-compat.
In order to start Questa with the graphical interface and for the simulator to remain active after the tests have completed, set GUI=1.
Users of the QIS/Qrun flow can set GUI=livesim to open Visualizer during the simulation in Live Simulation mode (an alias for GUI=1), or set GUI=postsim to open Visualizer after the simulation has ended (Post Simulation mode).
Starting with Questa 2022.3 and cocotb 1.7 users with VHDL toplevels can choose between two communication interfaces between Questa and cocotb: the proprietary FLI and VHPI.
For backwards-compatibility cocotb defaults to FLI.
Users can choose VHPI instead by setting the VHDL_GPI_INTERFACE environment variable to vhpi before running cocotb.
For more information, see Mentor/Siemens EDA ModelSim.
Reported Issues for this Simulator#
Mentor/Siemens EDA ModelSim#
In order to use this simulator, set SIM to modelsim:
make SIM=modelsim
This simulator is not currently supported in the Python Runner flow.
Note
A working installation of the simulator itself is required.
Any ModelSim PE or ModelSim PE derivatives (like the ModelSim Microsemi, Intel, Lattice Editions) do not support the VHDL FLI feature.
If you try to use them with FLI, you will see a vsim-FLI-3155 error:
** Error (suppressible): (vsim-FLI-3155) The FLI is not enabled in this version of ModelSim.
ModelSim DE and SE (and Questa, of course) support the FLI.
In order to start ModelSim with the graphical interface and for the simulator to remain active after the tests have completed, set GUI=1.
If you have previously launched a test without this setting, you might have to delete the SIM_BUILD directory (sim_build by default) to get the correct behavior.
Reported Issues for this Simulator#
Cadence Incisive#
In order to use this simulator, set SIM to ius:
make SIM=ius
This simulator is not currently supported in the Python Runner flow.
Note
A working installation of the simulator itself is required.
For more information, see Cadence Xcelium.
Reported Issues for this Simulator#
Cadence Xcelium#
In order to use this simulator, set SIM to xcelium:
make SIM=xcelium
# or
SIM=xcelium [...] pytest [...]
For simulator-specific limitations when running with the Python Runner flow,
see cocotb_tools.runner.Xcelium.
Note
A working installation of the simulator itself is required.
The simulator automatically loads VPI even when only VHPI is requested.
Testing designs with VHDL toplevels is only supported with Xcelium 23.09.004 and newer.
Reported Issues for this Simulator#
GHDL#
Note
cocotb supports GHDL 2.0+.
In order to use this simulator, set SIM to ghdl:
make SIM=ghdl
# or
SIM=ghdl [...] pytest [...]
For simulator-specific limitations when running with the Python Runner flow,
see cocotb_tools.runner.Ghdl.
Note
A working installation of GHDL is required. You can find installation instructions in the GHDL documentation.
Noteworthy is that despite GHDL being a VHDL simulator, it implements the VPI interface. This prevents cocotb from accessing some VHDL-specific constructs, like 9-value signals.
To specify a VHDL architecture to simulate, set the ARCH make variable to the architecture name.
Reported Issues for this Simulator#
Waveforms#
To get waveforms in VCD format, set the SIM_ARGS option to --vcd=anyname.vcd,
for example in a Makefile:
SIM_ARGS+=--vcd=anyname.vcd
The option can be set on the command line, as shown in the following example.
SIM_ARGS=--vcd=anyname.vcd make SIM=ghdl
A VCD file named anyname.vcd will be generated in the current directory.
SIM_ARGS can also be used to pass command line arguments related to other waveform formats supported by GHDL.
NVC#
Note
NVC version 1.11.0 or later is required.
Note
Using NVC versions greater than 1.16.0 will automatically add the --preserve-case option build commands.
This is standards-compliant behavior and may become default behavior in NVC, so think twice before overriding it.
In order to use this simulator, set SIM to nvc:
make SIM=nvc
# or
SIM=nvc [...] pytest [...]
For simulator-specific limitations when running with the Python Runner flow,
see cocotb_tools.runner.Nvc.
Reported Issues for this Simulator#
Coverage#
To enable code coverage, add --cover to SIM_ARGS, for example
in a Makefile:
SIM_ARGS += --cover
Specifying types of coverage is also supported. For example, to collect statement and branch coverage:
SIM_ARGS += --cover=statement,branch
The covdb files will be placed in the TOPLEVEL_LIBRARY subdirectory of SIM_BUILD.
For instructions on how to specify coverage types and produce a report, refer to NVC’s code coverage documentation.
Waveforms#
To get waveforms in FST format, set the SIM_ARGS option to --wave=anyname.fst, for example in a Makefile:
SIM_ARGS += --wave=anyname.fst
SIM_ARGS can also be used to set the waveform output to VCD by adding --format=vcd.
Tachyon DA CVC#
In order to use Tachyon DA’s CVC simulator,
set SIM to cvc:
make SIM=cvc
This simulator is not currently supported in the Python Runner flow.
Note
A working installation of the simulator itself is required.
Note that cocotb’s makefile is using CVC’s interpreted mode.
Reported Issues for this Simulator#
Siemens DSim#
Warning
DSim support for cocotb is experimental. Some features of cocotb may not work correctly or at all. At least DSim version 2025 is required.
In order to use this simulator, set SIM to dsim:
make SIM=dsim
# or
SIM=dsim [...] pytest [...]
For simulator-specific limitations when running with the Python Runner flow,
see cocotb_tools.runner.DSim.
Note
A working installation of DSim is required. You can install DSim simulator directly from Altair Marketplace and find information regarding getting a free license.
Waveforms#
DSim can produce waveform traces in the VCD format. They can be viewed with GTKWave or with Surfer.
To enable VCD tracing, set WAVES to 1.
make SIM=dsim WAVES=1
Reported Issues for this Simulator#
Added in version 2.0.