Written and maintained by CASRAI Editorial Board
Published
On this page
The gem5 simulator is an open-source, modular platform for computer-system architecture research: you describe a processor, memory system and board in Python configuration scripts, run a workload on that model, and read performance statistics from the files it writes. This guide takes you from the build requirements to a first run of the official tutorial script and then to reading stats.txt, with the commands taken from the current gem5 documentation (the v24.1 tutorial pages).
What gem5 is used for in research
gem5 is described by its project as a modular platform for computer-system architecture research, covering system-level architecture as well as processor microarchitecture. It began as the merger of two earlier academic simulators, m5 from the University of Michigan and GEMS from the University of Wisconsin, which were combined in 2011. It is distributed under a Berkeley-style license, so research groups can modify the source and share their changes.
Researchers use it to ask architecture questions without building hardware: how a cache or memory-system change affects run time, how a different core model behaves on the same workload, or how a new component interacts with an unmodified operating system. The 2020 paper describing the version 20.0+ line, written by 78 authors, characterises gem5 as an open-source, community-supported simulator that models hardware at the cycle level in enough detail to boot unmodified Linux and run full applications on x86, Arm and RISC-V. It reports more than 7,500 commits from over 250 contributors over nine years of development.
Instruction sets and CPU models
The gem5 about page lists support for the Alpha, ARM, SPARC, MIPS, POWER, RISC-V and x86 instruction sets. If the term is new to you, see the CASRAI guide to the instruction set architecture. For the processor itself gem5 offers several model families: a simple one-cycle-per-instruction CPU, a detailed in-order CPU, a detailed out-of-order CPU, a KVM-based CPU and a trace-driven (elastic) CPU. Choosing among them is a trade between simulation speed and modelling detail, and the right choice depends on the question your study asks.
Full-system mode versus application-only mode
gem5 runs in two modes. In full-system mode it simulates a complete machine and can boot an unmodified Linux kernel (the project lists this for ARM and x86), so operating-system effects, devices and boot behaviour are part of the experiment. In application-only mode it emulates Linux system calls for a single program, which avoids simulating an operating system at all. Use full-system mode when the operating system or devices matter to your result; use application-only mode when you want to study a single program’s behaviour on a simulated core and memory system.
How to install or access gem5
gem5 is built from source. The official documentation describes the build on Ubuntu, and the source is cloned from the project’s GitHub organisation. There is no installer to download.
Requirements
The build documentation lists these minimums: git 2.34 or newer, a GCC release from 11 up to 16, SCons 4.0 or newer, Python 3.10 or newer with its development headers, zlib 1.2 or newer and m4 1.4 or newer. Protocol Buffers 3.12 or newer and Boost 1.74 or newer are optional (Boost is for the SystemC integration). The same list is compiled as a dataset below the article so you can download it.
On Ubuntu, the documentation installs the dependencies with a single command:
sudo apt install build-essential git m4 scons zlib1g zlib1g-dev libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev python3-dev
Get the source and build
- Clone the repository:
git clone https://github.com/gem5/gem5 - Move into it:
cd gem5 - Build with SCons:
python3 `which scons` build/ALL/gem5.opt -j9
The -j value sets the number of parallel build jobs; the tutorial’s example of 9 is chosen as the number of CPU cores plus one, so adjust it to your machine. The target build/ALL/gem5.opt has three parts. build/ALL is the build variant: from v22.1 the ALL build includes every supported ISA, and from v24.1 it also includes every Ruby coherence protocol. Configuration of builds through Kconfig was added in v23.1. gem5.opt is the binary type. The documentation distinguishes three: debug, opt and fast. The fast binary has no symbols and has assertions removed, so it carries less debugging information than the other two.
How to run a first simulation step by step
The official tutorial’s first run uses a small configuration script rather than a hand-assembled system. This follows the v24.1 tutorial page; the older tutorial text in many course notes uses a different script, covered under version differences below.
- Build gem5 as above so that
build/ALL/gem5.optexists. - Open
configs/tutorial/part1/simple.pyin the source tree. It creates anX86DemoBoard, obtains a prebuilt disk-image resource withobtain_resource("x86-ubuntu-24.04-boot-no-systemd"), creates aSimulator(board)and callssim.run(20_000_000_000). - Run the script with the gem5 binary:
./build/ALL/gem5.opt configs/tutorial/part1/simple.py
The 20,000,000,000 passed to run is a count of simulated ticks. The tutorial states it as 20 milliseconds of simulated time, which is consistent with the global frequency the run reports of 1,000,000,000,000 ticks per second. The simulator therefore stops after 20 ms of simulated time, not after a wall-clock interval.
The board name carries a warning. gem5 prints a message that X86DemoBoard is for demonstration only, so treat this first run as a check that your build and toolchain work. For a real study you replace the demonstration board with components that match what you want to model.
Version differences that trip people up
Search results and course pages still show the version 21.0 tutorial script. That script built a System() by hand, used an X86TimingSimpleCPU() and a DDR3_1600_8x8() memory controller, and printed “Hello world!” from a small test program. The v24.1 script uses the board and Simulator interface instead and boots a Linux disk image. If a command in an older tutorial does not match the current source tree, check which gem5 version the tutorial was written for before debugging anything else.
How to read the gem5 output
When the run starts, the console prints a banner that includes the version (the v24.1 tutorial shows gem5 version 24.1.0.0), a line that the global frequency is set at 1000000000000 ticks per second, and finally Entering event queue @ 0. Starting simulation..., which marks the start of the simulated timeline.
gem5 writes its results to an output directory named m5out. The tutorial identifies three files you will open most often:
| File | What it contains |
|---|---|
config.ini |
Every SimObject created for the run with all of its parameters, including defaults you never set |
config.json |
The same configuration in JSON, convenient for scripts |
stats.txt |
The statistics. Each dump starts with ---------- Begin Simulation Statistics ----------, and a run can contain several dumps |
Keep config.ini or config.json with your results. Because they record parameters you did not set explicitly, they are the record of what you actually simulated, which is what a reader or a replication attempt needs.
Three statistics to find first
simSeconds: the number of seconds simulated. It is simulated time, so it is the basis for comparing performance between configurations.simInsts: the number of instructions simulated, as a count.hostInstRate: the simulator’s instruction rate in instructions per second of real time. It measures how fast your host machine runs the simulator, not how fast the simulated machine is, so never compare it withsimSeconds-based results.
Statistic types
The gem5 statistics documentation lists the types a statistic can take: Scalar, Average, Vector, Distribution, Histogram, SparseHistogram and Formula. It also lists output flags including nozero, nonan, pdf and cdf. When a stat looks unfamiliar in stats.txt, its type tells you whether you are reading a single count, an average, a per-element vector or a distribution.
Troubleshooting gem5
The build documentation covers one failure in detail: errors that involve Protocol Buffers. The recommended fix is to clean the SCons state without its cache and rebuild:
python3 `which scons` --clean --no-cache
and then run the build command again. If that does not clear it, the documentation’s fallback is to delete the whole build directory (rm -rf build/) and rebuild from scratch.
Two further checks avoid most other early problems, and both follow from the requirements above. First, confirm that your compiler and Python versions fall within the listed ranges before building, because the minimums are strict. Second, confirm you are following instructions for the same gem5 version you cloned: the ALL build variant, the Kconfig-based configuration and the board-style scripts were introduced in different releases, so an older walkthrough can name a path that does not exist in your tree.
Free alternatives to gem5
gem5 is itself free and open source, so the question is whether a different simulator fits your study better. Two other open tools describe themselves differently from gem5, and the table below states only what each project says about itself.
| Tool | How the project describes it | How you run it |
|---|---|---|
| ChampSim | An open-source trace-based simulator for microarchitecture study; replays instruction traces, lets you add branch predictors, data prefetchers and replacement policies, and reports IPC (instructions per cycle). Apache-2.0 licensed | Configure with ./config.sh, compile with make, then run bin/champsim with warmup and simulation instruction counts and a trace |
| SST (Structural Simulation Toolkit) | A simulation toolkit for exploring innovations in highly concurrent systems, with a fully modular design and an MPI-based parallel simulation environment for looking at large systems | See the SST site for installation and use |
| gem5 (for comparison) | A modular platform for computer-system architecture research that can run full-system or application-only workloads | Build from source and run a configuration script, as above |
The practical difference visible in these descriptions is the input. ChampSim replays recorded traces, whereas gem5 can execute a program or boot a Linux image on the simulated machine. SST’s own description emphasises modularity and parallel simulation of large systems. None of the three pages claims that one is faster or more accurate than another, so any such comparison for your study needs your own measurements. If your question is about a discrete-event model of a process rather than a hardware design, a general framework such as SimPy for discrete-event simulation is a different kind of tool.
Reporting gem5 results reproducibly
A simulator result is only reusable if someone else can regenerate it. For a gem5 study that means recording the gem5 version or commit you built, the build target (for example build/ALL/gem5.opt), the configuration script, and the config.json from m5out. The gem5 project asks users to cite its publications, and the about page points to its Publications page for that. For the wider practice of capturing code, containers and workflows, see the CASRAI guide on reproducibility infrastructure. When you evaluate a design against workloads you did not write, state which workloads you used, and see the synthetic benchmark definition for how synthetic workloads differ from real applications.
Sources
- gem5 project: About
- Learning gem5, Part 1: Building gem5
- Learning gem5, Part 1: Creating a simple configuration script
- Learning gem5, Part 1: Understanding gem5 statistics and output
- gem5 documentation: Statistics
- The gem5 Simulator: Version 20.0+ (arXiv:2007.03152)
- ChampSim repository
- Structural Simulation Toolkit (SST)
Data: gem5 build requirements and minimum versions (v24.1 documentation)
Minimum versions of the tools and libraries needed to build gem5 from source, compiled from the official Learning gem5 building page, with whether each is required or optional.
Period covered: 2024/2026.
| Component | Minimum version | Requirement | Note |
|---|---|---|---|
| git | 2.34 | Required | Used to clone the repository |
| GCC | 11 (up to 16) | Required | Supported compiler range |
| SCons | 4.0 | Required | Build system |
| Python development headers | 3.10 | Required | Python 3.10 or newer with dev headers |
| zlib | 1.2 | Required | Compression library |
| m4 | 1.4 | Required | Macro processor |
| Protocol Buffers | 3.12 | Optional | Protobuf-related build features |
| Boost | 1.74 | Optional | Needed for SystemC integration |
Sources
- Learning gem5, Part 1: Building gem5 (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







