Building gem5


If compiling gem5 on Debian, Ubuntu, or related Linux distributions, you may install all these dependencies using APT:

sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \
    libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \
    python-dev python libboost-all-dev

Getting the code

git clone

Building with SCons

gem5’s build system is based on SCons, an open source build system implemented in Python. You can find more information about scons at The main scons file is called SConstruct and is found in the root of the source tree. Additional scons files are named SConscript and are found throughout the tree, usually near the files they’re associated with.

Within the root of the gem5 directory, gem5 can be built with SCons using:

scons build/{ISA}/gem5.{variant} -j {cpus}

where {ISA} is the target (guest) Instruction Set Architecture, and {variant} specifies the compilation settings. For most intents and purposes opt is a good target for compilation. The -j flag is optional and allows for parallelization of compilation with {cpus} specifying the number of threads. A single-threaded compilation from scratch can take up to 2 hours on some systems. We therefore strongly advise allocating more threads if possible.

The valid ISAs are:

The valid build variants are:

These versions are summarized in the following table.

Build variant Optimizations Run time debugging support Profiling support
debug   X  
opt X X  
fast X    
prof X   X
perf X   X

For example, to build gem5 on 4 threads with opt and targeting x86:

scons build/X86/gem5.opt -j 4


Once compiled, gem5 can then be run using:

./build/{ISA}/gem5.{variant} [gem5 options] {simulation script} [script options]

Running with the --help flag will display all the available options:

  gem5.opt [gem5 options] [script options]

gem5 is copyrighted software; use the --copyright option for details.

--version               show program's version number and exit
--help, -h              show this help message and exit
--build-info, -B        Show build information
--copyright, -C         Show full copyright information
--readme, -R            Show the readme
--outdir=DIR, -d DIR    Set the output directory to DIR [Default: m5out]
--redirect-stdout, -r   Redirect stdout (& stderr, without -e) to file
--redirect-stderr, -e   Redirect stderr to file
--stdout-file=FILE      Filename for -r redirection [Default: simout]
--stderr-file=FILE      Filename for -e redirection [Default: simerr]
                        Port (e.g., gdb) listener mode (auto: Enable if
                        running interactively) [Default: auto]
                        Port listeners will only accept connections over the
                        loopback device
--interactive, -i       Invoke the interactive interpreter after running the
--pdb                   Invoke the python debugger before running the script
--path=PATH[:PATH], -p PATH[:PATH]
                        Prepend PATH to the system path when invoking the
--quiet, -q             Reduce verbosity
--verbose, -v           Increase verbosity

Statistics Options
--stats-file=FILE       Sets the output file for statistics [Default:
--stats-help            Display documentation for available stat visitors

Configuration Options
--dump-config=FILE      Dump configuration output file [Default: config.ini]
--json-config=FILE      Create JSON output of the configuration [Default:
--dot-config=FILE       Create DOT & pdf outputs of the configuration
--dot-dvfs-config=FILE  Create DOT & pdf outputs of the DVFS configuration
                        [Default: none]

Debugging Options
                        Create breakpoint(s) at TICK(s) (kills process if no
                        debugger attached)
--debug-help            Print help on debug flags
                        Sets the flags for debug output (-FLAG disables a
--debug-start=TICK      Start debug output at TICK
--debug-end=TICK        End debug output at TICK
--debug-file=FILE       Sets the output file for debug [Default: cout]
--debug-ignore=EXPR     Ignore EXPR sim objects
                        Remote gdb base port (set to 0 to disable listening)

Help Options
--list-sim-objects      List all built-in SimObjects, their params and default


The EXTRAS scons variable can be used to build additional directories of source files into gem5 by setting it to a colon delimited list of paths to these additional directories. EXTRAS is a handy way to build on top of the gem5 code base without mixing your new source with the upstream source. You can then manage your new body of code however you need to independently from the main code base.