# Installation

This section discusses how to install Verilator.

## Package Manager Quick Install

Using a distribution’s package manager is the easiest way to get started. (Note distribution packages almost never have the most recent Verilator version, so we recommend following Git Quick Install below, instead.) To install as a package:

    apt-get install verilator   # On Ubuntu

For other distributions, refer to Repology Verilator Distro Packages.

## Pre-commit Quick Install

You can use Verilator’s pre-commit hook to lint your code before committing it. It encapsulates the Verilator Build Docker Container, so you need docker on your system to use it. The verilator image will be downloaded automatically.

To use the hook, add the following entry to your `.pre-commit-config.yaml`:

    repos:
      - repo: https://github.com/verilator/verilator
        rev: v5.026  # or later
        hooks:
          - id: verilator

## Git Quick Install

Installing Verilator from Git provides the most flexibility; for additional options and details, see Detailed Build Instructions below.

In brief, to install from git:

    # Prerequisites:
    #sudo apt-get install git help2man perl python3 make autoconf g++ flex bison ccache
    #sudo apt-get install libgoogle-perftools-dev libjemalloc-dev numactl perl-doc
    #sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
    #sudo apt-get install libfl-dev  # Ubuntu only (ignore if gives error)
    #sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)

    git clone https://github.com/verilator/verilator   # Only first time

    # Every time you need to build:
    unsetenv VERILATOR_ROOT  # For csh; ignore error if on bash
    unset VERILATOR_ROOT  # For bash
    cd verilator
    git pull         # Make sure git repository is up-to-date
    git tag          # See what versions exist
    #git checkout master      # Use development branch (e.g. recent bug fixes)
    #git checkout stable      # Use most recent stable release
    #git checkout v{version}  # Switch to specified release version

    autoconf         # Create ./configure script
    ./configure      # Configure and create Makefile
    make -j `nproc`  # Build Verilator itself (if error, try just 'make')
    sudo make install

## Detailed Build Instructions

This section describes details of the build process and assumes you are building from Git. For using a pre-built binary for your Linux distribution, see instead Package Manager Quick Install.

### OS Requirements

Verilator is developed and has primary testing on Ubuntu, with additional testing on Apple OS-X, FreeBSD and Windows MSVC. Versions have also been built on Red Hat Linux, other flavors of GNU/Linux-ish platforms, Windows Subsystem for Linux (WSL2), Windows under Cygwin, and Windows under MinGW (gcc -mno-cygwin).

### Install Prerequisites

To build or run Verilator, you need these standard packages:

    sudo apt-get install git help2man perl python3 make
    sudo apt-get install g++  # Alternatively, clang
    sudo apt-get install libgz  # Non-Ubuntu (ignore if gives error)
    sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
    sudo apt-get install libfl-dev  # Ubuntu only (ignore if gives error)
    sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)

For SystemC:

    sudo apt-get install libsystemc libsystemc-dev

For constraints:

    sudo apt-get install z3  # Optional solver

The following is optional but is recommended for nicely rendered command line help when running Verilator:

    sudo apt-get install perl-doc

To build or run Verilator, the following are optional but should be installed for good performance:

    sudo apt-get install ccache  # If present at build, needed for run
    sudo apt-get install mold  # If present at build, needed for run
    sudo apt-get install libjemalloc-dev numactl

To build Verilator you will need to install these packages; these do not need to be present to run Verilator:

    sudo apt-get install git autoconf flex bison

Those developing Verilator itself also need the following additional packages (see internals.rst), and a Python virtual environment:

    sudo apt-get install clang clang-format-18 cmake gdb gprof graphviz lcov
    sudo apt-get install python3-clang bear jq
    cpan install Pod::Perldoc

The Python virtual environment is only required for running the whole test suite, and for additional development steps like linting and formatting. It is not required for building Verilator itself. To install the python virtual environment and all dependencies automatically, run the following once, after `configure`:

    # Create Python virutal environment in .venv:
    make venv

    # Or alternatively, to put it somewhere else:
    make venv VENV_PATH=where_you_want_it

Then activate the virtual environment in the shell using:

    source .venv/bin/activate

    # Or if installed somewhere else:
    source where_you_want_it/bin/activate

#### Install SystemC

SystemC code can be generated from Verilator (with `--sc`) if it is installed as a package (see above).

Alternatively, from their sources, download SystemC. Follow their installation instructions. You will need to set the `SYSTEMC_INCLUDE` environment variable to point to the include directory with `systemc.h` in it, and set the `SYSTEMC_LIBDIR` environment variable to point to the directory with `libsystemc.a` in it.

#### Install GTKWave

To make use of Verilator FST tracing you will want GTKwave installed, however this is not required at Verilator build time.

    sudo apt-get install gtkwave  # Optional Waveform viewer

#### Install Z3

In order to use constrained randomization the Z3 Theorem Prover must be installed, however this is not required at Verilator build time. There are other compatible SMT solvers, like CVC5/CVC4, but they are not guaranteed to work. Since different solvers are faster for different scenarios, the solver to use at run-time can be specified by the environment variable `VERILATOR_SOLVER`.

### Obtain Sources

Get the sources from the git repository: (You need to do this only once, ever.)

    git clone https://github.com/verilator/verilator   # Only first time
    ## Note the URL above is not a page you can see with a browser; it's for git only

Enter the checkout and determine what version/branch to use:

    cd verilator
    git pull        # Make sure we're up-to-date
    git tag         # See what versions exist
    #git checkout master      # Use development branch (e.g. recent bug fix)
    #git checkout stable      # Use most recent release
    #git checkout v{version}  # Switch to specified release version

### Auto Configure

Create the configuration script:

    autoconf        # Create ./configure script

### Eventual Installation Options

Before configuring the build, you must decide how you’re going to eventually install Verilator onto your system. Verilator will be compiling the current value of the environment variables `VERILATOR_ROOT`, `VERILATOR_SOLVER`, `SYSTEMC_INCLUDE`, and `SYSTEMC_LIBDIR` as defaults into the executable, so they must be correct before configuring.

These are the installation options:

#### 1. Run-in-Place from VERILATOR_ROOT

Our personal favorite is to always run Verilator in-place from its Git directory (don’t run `make install`). This allows the easiest experimentation and upgrading, and allows many versions of Verilator to co-exist on a system.

    export VERILATOR_ROOT=`pwd`   # if your shell is bash
    setenv VERILATOR_ROOT `pwd`   # if your shell is csh
    ./configure
    # Running will use files from $VERILATOR_ROOT, so no install needed

Note after installing (see ref:Installation), a calling program or shell must set the environment variable `VERILATOR_ROOT` to point to this Git directory, then execute `$VERILATOR_ROOT/bin/verilator`, which will find the path to all needed files.

#### 2. Install into a Specific Prefix

You may be an OS package maintainer building a Verilator package, or you may eventually be installing onto a project/company-wide “CAD” tools disk that may support multiple versions of every tool. Tell configure the eventual destination directory name. We recommend that the destination location include the Verilator version name:

    unset VERILATOR_ROOT      # if your shell is bash
    unsetenv VERILATOR_ROOT   # if your shell is csh
    # For the tarball, use the version number instead of git describe
    ./configure --prefix /CAD_DISK/verilator/`git describe | sed "s/verilator_//"`

Note after installing (see ref:Installation), you need to add the path to the `bin` directory to your `PATH`. Or, if you use modulecmd, you’ll want a module file like the following:

    set install_root /CAD_DISK/verilator/{version-number-used-above}
    unsetenv VERILATOR_ROOT
    prepend-path PATH $install_root/bin
    prepend-path MANPATH $install_root/man
    prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig

#### 3. Install System Globally

The final option is to eventually install Verilator globally, using configure’s default system paths:

    unset VERILATOR_ROOT      # if your shell is bash
    unsetenv VERILATOR_ROOT   # if your shell is csh
    ./configure

Then after installing (see ref:Installation), the binaries should be in a location already in your `$PATH` environment variable.

### Configure

The command to configure the package was described in the previous step. Developers should configure to have more complete developer tests. Additional packages may be required for these tests.

    export VERILATOR_AUTHOR_SITE=1    # Put in your .bashrc
    ./configure --enable-longtests  ...above options...

### Compile

Compile Verilator:

    make -j `nproc`  # Or if error on `nproc`, the number of CPUs in system

### Test

Check the compilation by running self-tests:

    make test

### Install

If you used any install option other than the 1. Run-in-Place from VERILATOR_ROOT scheme, install the files:

    make install

## Verilator Build Docker Container

This Verilator Build Docker Container is set up to compile and test a Verilator build. It uses the following parameters:

- Source repository (default: https://github.com/verilator/verilator)

- Source revision (default: master)

- Compiler (GCC 13.3.0, clang 18.1.3, default: 13.3.0)

The container is published as `verilator/verilator-buildenv` on docker hub.

To run the basic build using the current Verilator master:

    docker run -ti verilator/verilator-buildenv

To also run tests:

    docker run -ti verilator/verilator-buildenv test

To change the compiler use the -e switch to pass environment variables:

    docker run -ti -e CXX=clang++-18 verilator/verilator-buildenv test

The tests, that involve numactl are not working due to security restrictions. To run those too, add the CAP_SYS_NICE capability during the start of the container:

    docker run -ti --cap-add=CAP_SYS_NICE verilator/verilator-buildenv test

Rather then building using a remote git repository you may prefer to use a working copy on the local filesystem. Mount the local working copy path as a volume and use that in place of git. When doing this be careful to have all changes committed to the local git area. To build the current HEAD from top of a repository:

    docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` verilator/verilator-buildenv test

### Rebuilding

To rebuild the Verilator-buildenv docker image, run:

    docker build .

This will also build SystemC under all supported compiler variants to reduce the SystemC testing time.

## Verilator Executable Docker Container

The Verilator Executable Docker Container allows you to run Verilator easily as a docker image, e.g.:

    docker run -ti verilator/verilator:latest --version

This will pull the container from Docker Hub, run the latest Verilator and print Verilator’s version.

Containers are automatically built and pushed to docker hub for all released versions, so you may easily compare results across versions, e.g.:

    docker run -ti verilator/verilator:4.030 --version

Verilator needs to read and write files on the local system. To simplify this process, use the `verilator-docker` convenience script. This script takes the version number, and all remaining arguments are passed through to Verilator. e.g.:

    ./verilator-docker 4.030 --version

or

    ./verilator-docker 4.030 --cc test.v

If you prefer not to use `verilator-docker` you must give the container access to your files as a volume with appropriate user rights. For example to Verilate test.v:

    docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:latest --cc test.v

This method can only access files below the current directory. An alternative is setup the volume `-workdir`.

You can also work in the container by setting the entrypoint (don’t forget to mount a volume if you want your work persistent):

    docker run -ti --entrypoint /bin/bash verilator/verilator:latest

You can also use the container to build Verilator at a specific commit:

    docker build --build-arg SOURCE_COMMIT=<commit> .

### Internals

The Dockerfile builds Verilator and removes the tree when completed to reduce the image size. The entrypoint is a wrapper script (`verilator-wrap.sh`). That script 1. calls Verilator, and 2. copies the Verilated runtime files to the `obj_dir` or the `-Mdir` respectively. This allows the user to have the files to they may later build the C++ output with the matching runtime files. The wrapper also patches the Verilated Makefile accordingly.

A hook is also defined and run by Docker Hub via automated builds.