VUnit: a unit test framework that speaks VHDL and SystemVerilog

A test early and often approach for hardware

VUnit is an open source unit testing framework for VHDL/SystemVerilog, and the README states the goal plainly: to feature the functionality needed to realize continuous and automated testing of your HDL code.

The interesting sentence is the second one. VUnit does not replace but rather complements traditional testing methodologies, by supporting a test early and often approach through automation. That positioning is deliberate and it is the key to understanding the framework. A full UVM style environment is a large investment that pays off on large projects with complex stimulus requirements. VUnit takes the other end of the scale, making the smallest possible test cheap enough to write for every module, so that the regression suite grows alongside the design rather than appearing at the end.

The audience is therefore FPGA and ASIC engineers who already write HDL and want the test discipline of software unit testing applied to their design files. The topic tags on the repository list asic, fpga, verilog-hdl, vhdl, systemverilog-hdl, testbench, verification, unit-testing and universal-verification-methodology, and the keywords in the package metadata add uvm and eda alongside vhdl, verilog-hdl and fpga.

The authors are Lars Asplund and Olof Kraigher, and the homepage is vunit.github.io with an about page that expands on the philosophy. The package is published to PyPI as vunit_hdl.

The repository layout reflects a mature project rather than a script collection. There is a vunit directory with subpackages for the command interface, the parser with separate VHDL and Verilog handling, the simulator interface layer, the test framework and the user interface, plus docs, examples with separate verilog and vhdl directories, tests, tools and an AGENTS.md.

Simulator independence as the core design decision

The mechanism that makes VUnit different from a vendor library is a simulator interface layer, and the pyproject.toml makes its structure explicit. The packages included in the distribution are vunit, vunit.com, vunit.parsing, vunit.parsing.verilog, vunit.sim_if, vunit.test and vunit.ui.

The sim_if package is the abstraction over simulators. A test written against VUnit does not talk to a specific simulator, so the same testbench can be run on whichever simulator your team licenses, or on several, which is how you check that a design is not relying on one tool's quirks. The parsing package, with a separate verilog submodule, handles reading HDL source and the testbench structure rather than relying on a simulator to do it.

The test package holds the test framework itself, and the ui package the reporting layer, which is where the familiar pass and fail output and the code coverage report come from.

The distribution also ships files that are not Python at all. The setup script collects every .tcl file under the vunit directory, the VHDL sources under vunit/vhdl, and the .v, .sv and .svh files under vunit/verilog, and installs them as package data. Those are the OSVVM library sources and the simulator interface Tcl scripts, which is how a Python package ends up carrying a VHDL verification library and the glue that drives a simulator from it.

This is also why the framework is not just a Python library with assertions. The assertion and logging library and the scoreboard helpers are part of the shipped VHDL, and the framework drives them through a simulator.

Installing from PyPI or from a repository with OSVVM

The package is on PyPI as vunit_hdl and installs with pip, and the project requires Python 3.10 or newer, with classifiers for 3.10 through 3.14 and for Windows, macOS and Linux. The only runtime dependencies are colorama, and tomli for Python versions below 3.11.

Installing from a git repository has one extra step, and the setup script warns about it explicitly. If OSVVM is not present, it prints a message saying that if you are installing from a Git repository and plan to use VUnit's integration of OSVVM you should run:

git submodule update --init --recursive

in your VUnit repository before running setup.py. The OSVVM library is included as a git submodule, and the .gitmodules file at the repository root confirms it. This is the single most common friction point for a new user, and the warning is printed at install time precisely so it is not a mystery later.

The setup script also reads the version from vunit.about, so the version lives in the source rather than in a duplicated field. The pyproject.toml declares the version as dynamic for that reason, and the project uses towncrier for changelog fragments, with news entries in docs/news.d/ and the generated file docs/news.inc.

The source layout is modern for an HDL tool. The pyproject.toml builds with setuptools 77 or newer, the project is black formatted with a line length of 120, and there are GitHub Actions workflows for docs, images, push and coverage, which is where the continuous and automated testing of the framework itself happens.

OSVVM without the methodology overhead

The OSVVM integration deserves its own attention because it is the part of VUnit that is most often misunderstood.

OSVVM is a VHDL verification library with a mature assertion, logging, scoreboard and randomization capability set. It is the closest thing the open source HDL world has to a standard library of verification building blocks, and it predates VUnit. What VUnit adds is the ability to use those building blocks from Python, with a Python API for the test cases themselves.

The consequence is that you can write a test case as a Python method with a decorator marking it as a test, and inside it call into the VHDL library for logging and assertions through the shipped Tcl scripts. The test framework drives the simulator, parses the results, and reports pass or fail with the log output. The framework is not calling the simulator's own scripting API for everything, it is running a controlled simulation with an OSVVM based testbench and reading the structured output.

The reason to care is portability. A testbench written against a vendor's TCL API, or against a vendor library, ties you to that vendor. A testbench built on OSVVM and driven by VUnit can be re-run on a different simulator without rewriting the test, which is a meaningful saving for a team that might want to check a design against two tools before tapeout.

The alternatives are worth naming precisely. A vendor supplied unit test framework is tied to the simulator you already pay for, and usually cannot run on a competitor's tool. A Python script driving the simulator directly, with no framework, is what most teams write first and it works until the test count grows. UVM is a different category entirely, a full constrained random methodology with classes, factories and sequences, and adopting it for a handful of module tests is the kind of overhead VUnit exists to avoid.

Where the framework stops, and the constraints that come with it

Two constraints are visible in the repository itself rather than in the documentation.

The first is the submodule. OSVVM is a git submodule, so a source install needs an extra git step, and the setup script warns when it detects the library is missing. Any pipeline that clones the repository with a shallow, no-submodules checkout will hit this.

The second is the Python requirement. Python 3.10 or newer, and the tomli dependency for anything below 3.11, means the framework itself will not run on the older interpreters still present in some FPGA shops. That is a reasonable trade for a modern tool, but it does mean a legacy build image needs updating before VUnit can be adopted.

There is also a documentation limit worth naming. The README is short, a handful of paragraphs plus badges, and points to vunit.github.io for the about page and the contributing guide. The detailed API reference, the tutorial pages and the FAQ live on the documentation site rather than in the repository, so the repository alone is not enough to evaluate the framework's full capabilities. That is a reasonable choice for a project with a real docs site, and the docs workflow badge in the README shows the documentation is built in CI rather than hand-maintained.

For a framework like this, the practical risk is not a bug in the code. It is the fit between your design style and the framework's assumptions about testbench structure. VUnit expects you to structure your tests around its API, with Python driving and VHDL libraries providing the checks. Teams whose existing testbenches are large standalone HDL files will find adoption more work than a greenfield module would.

Maintenance, licence and the version picture

The repository is not archived and the last push was on 2026-10-16, so work on the framework is continuing. The listed releases are v4.7.0 from 2023-04-23, v4.6.0 from 2021-10-25 and v4.5.0 from 2021-05-21, and the README carries a badge for commits since the latest release, which is the sort of thing a project with regular post-release commits maintains.

The gap between the release tags and the last push date is worth understanding rather than worrying about. The README links to the releases page for that badge, and the documentation site hosts the news entries, so a user following the documentation is kept current on changes even between formal tags.

The licence is MPL-2.0. The pyproject.toml declares it and points the license-files entry at LICENSE.rst, and the setup script carries the Mozilla Public License 2.0 header. MPL is a file level copyleft licence, which is a good fit for a tool of this kind: if you modify VUnit and distribute your modified version, those modified files must stay open, while the rest of your codebase is unaffected. It is a much lighter obligation than a whole project copyleft, and it does not reach the HDL you write or the designs you verify with it.

The metadata classifies the project as Development Status :: 5 - Production/Stable, and the topic classifiers point at Electronic Design Automation and Software Development Testing. For a framework in a niche that is often home grown, a production stable classification from the maintainers is a reasonable signal, though the specific version you install is what matters, not the classifier.

Editorial conclusion

Adopt VUnit if you write VHDL or SystemVerilog and want repeatable, simulator independent unit tests plus code coverage, and if you are willing to build your own testbenches in Python rather than a vendor specific library. Do not adopt it as a replacement for a full UVM environment, since the README positions VUnit as complementing traditional methodologies rather than replacing them. Verify first that your simulator is on the supported list, that OSVVM is initialised as a git submodule if you installed from a repository, and that the Python version on your machine satisfies the 3.10 or newer requirement.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. VUnit/vunit on GitHub