Geant4: twenty years of particle transport simulation, still installing from source

What Geant4 is actually for

Geant4 is a toolkit for the simulation of the passage of particles through matter. The areas of application it names are high energy, nuclear and accelerator physics, as well as studies in medical and space science. That last pair is the one worth pausing on, because it tells you the toolkit is not confined to collider detectors. The same transport engine that follows a proton through a detector is what a medical physicist uses to model dose in tissue, and what a space scientist uses to model shielding and particle flux in a spacecraft. The subject matter is the passage of particles through matter, and the geometry, the physics and the scoring are the three parts that follow from that. The site's own description points to the Geant4 website for how to use it and what its application domains are.

The three papers that define the toolkit

The project names three main reference papers, and the dates span more than a decade. The earliest is Nuclear Instruments and Methods in Physics Research A 506 (2003) 250-303, which is also the citation carried in the repository description. The second is IEEE Transactions on Nuclear Science 53 No. 1 (2006) 270-278. The third, and the most recent, is Nuclear Instruments and Methods in Physics Research A 835 (2016) 186-225. Reading three papers from 2003, 2006 and 2016 as the canonical description of the toolkit tells you something about how slowly the core ideas move and how much they have mattered. If you are writing a methods section that uses Geant4, these are the citations the field expects, and the choice of which ones to cite usually reflects which generation of the toolkit you built against.

Installation is a configuration exercise, not a package fetch

The installation section is short and it sends you elsewhere, because the real material is long. For detailed instructions on building and installing Geant4, including all supported platforms and configuration options, the pointer is to the Installation Guide. That phrasing, all supported platforms and configuration options, is a signal about the shape of the task. Geant4 is built with CMake, the repository carries a CMakeLists.txt at the root plus a cmake directory, and the configuration options are the physics selections you make at configure time. There is also an environments directory, which is where such a toolkit usually keeps its build presets, and a packaging directory. So the work is: obtain a source tree, run a configure step that selects the physics and the data you need, and build. The Installation Guide exists because the matrix of platforms and options is too large to summarise.

Where the documentation actually lives

Full documentation, including installation, use of the toolkit in applications, physics lists and physics model implementations, is on the User Documentation Site. That list is the architecture in one sentence. Physics lists are how you say which processes are active for a given particle and energy range, and physics models are the implementations behind them, so the toolkit separates the choice of physics from the code that implements it. That separation is why the toolkit can serve particle physics, medical physics and space physics at once, and it is also why the documentation has to be organised around it. For questions and issues, the project asks you to post on the User Forum in the category and section relevant to the problem, and notes that the forum is fully searchable, so the answer may already be there. Bug reports go to a separate Bugzilla tracker.

The examples tree and what the HowToRun files are for

The repository root includes an examples directory, and inside it there is a basic, an extended and an advanced tier, along with three documents: a README explaining the examples generally, a README.HowToRun.md and a README.HowToRunMT.md. The distinction between the two HowToRun files is the one to notice. A multi-threaded run is not simply the same run with a flag; in a transport simulation the work divides across the geometry and the physics, and the way the event loop is parallelised changes how results are collected and how the run is configured. So having separate guides for the single-threaded and multi-threaded paths means the project treats threading as a configuration question the user has to answer, not as an optimisation it applies for you. The tiers then build on each other: the basic examples establish the shape of an application, the extended ones add physics complexity, and the advanced ones cover the cases where you need to reach into the toolkit's own machinery.

Release lines: a stable branch and a beta running together

The recent releases show two tracks in flight at once. v11.4.3 was published on 2026-10-01 and v11.4.2 on 2026-06-17, both on the 11.4 line, and v11.5.0.beta was published on 2026-06-26. The three-part version number is the pattern to get used to, and the presence of a beta in the same release list means the two lines have different support characteristics even when they share a major version. For a scientific toolkit this matters more than it would for a library, because a physics result depends on the exact version of the toolkit and the data that produced it, so a paper that cites a Geant4 result usually has to say which release and which configuration. The repository keeps a ReleaseNotes directory and a CHANGELOG file for that history, and a CITATION.cff file for citation metadata.

The repository layout and the tooling around it

The top-level listing describes a large, long-lived project. There is a source directory holding the toolkit itself, a CMakeLists.txt with a cmake directory for the build system, a config directory, an examples directory, and an environments directory. Alongside those are the files a project accumulates over two decades: a CHANGELOG file, a CONTRIBUTING.rst, a LICENSE file, a CITATION.cff, and a ReleaseNotes directory. The source tree also carries both a.clang-format and a.clang-tidy configuration, so the code style and the static analysis rules are enforced from the repository rather than left to each contributor's editor. There are two continuous integration configurations visible, a.github directory and a.gitlab directory, which is a detail that dates the project and says something about how many institutions contribute to it. The whole repository is the source distribution, with no packaging for a language package manager.

Where Geant4 is the wrong choice

Four limits apply. It is a source-built C++ framework, so adopting it means a configure step, a compile of a large codebase and a data setup, which is a lot of ceremony for anything that could be done with an analytic formula or a much smaller library. The physics model you select at configure time is baked into the build, so changing what you simulate is not a runtime option but a rebuild, and that is a different workflow from swapping a Python dependency. The support model is a searchable forum and a Bugzilla tracker rather than a modern issue tracker with a service level, which for an industrial or clinical user is a procurement question rather than a technical one. And the licence is the one to settle first: the repository's licence field carries a custom classification that GitHub cannot label, so the LICENSE file in the root is the document that governs, and it should be read before a simulator goes near a regulated workflow.

Editorial conclusion

Use Geant4 when you need a Monte Carlo transport simulation of particles through real geometry with detector physics on top, because it is the reference toolkit in that field and the physics models are the point of it. Do not adopt it for a quick calculation, since it is a large C++ framework you compile and configure, and the licensing is a custom one rather than a standard permissive licence you can assume. Verify first which release series you build against, since 11.4.3 and an 11.5.0 beta were both published recently, that your platform is on the supported list in the Installation Guide, and that you read the LICENSE file directly, because the repository's licence field carries a custom classification that GitHub cannot label.

Frequently asked questions

Official sources

1. Geant4/geant4 on GitHub
2. Issues
3. Project website
4. README
5. Releases