Ninja: a build system that trades readable build files for speed

The problem Ninja solves is build execution, not build description

Ninja is a build system with a focus on speed, and the repository describes it as small. Those two words explain the design. Ninja does not try to be the place where you describe your project. It reads a build graph, checks timestamps and runs commands, and it tries to do that with as little overhead as possible. The README does not present Ninja as a Make replacement you author by hand; it points to the manual for background and details, and the project's own build is generated by configure.py or CMake before Ninja is used at all. That is the intended shape of the tool. A higher-level generator, CMake and Meson being the obvious examples in general use, writes build.ninja, and Ninja executes it. If you are choosing Ninja, you are choosing the executor, not the language you write your build in. The audience is therefore teams whose build description already lives in a generator and who want the part that runs commands to stop being the slow part. A single developer with a five-file project and a hand-written Makefile is not the audience, and the README does not pretend otherwise.

How the ninja binary and build.ninja fit together

The data flow is short. A generator produces build.ninja, a file of build statements that name inputs, outputs and the command that connects them. Ninja loads that file, builds an internal graph, and schedules commands. It re-reads the build file when a generator declares itself as a dependency, which is how CMake regenerates build.ninja when CMakeLists.txt changes. The repository layout reflects the split: src/ holds the C++ implementation, doc/ holds the manual sources, configure.py is the Python bootstrap generator, and CMakeLists.txt is the alternative. The README is explicit that Ninja is a standalone executable, not a library, and that there is no public API even though the Doxygen output documents internal details. That matters if you were hoping to embed Ninja in another program: the project does not offer that. The binary is the interface. Everything else, including how dependency information is discovered and how the graph is constructed, belongs to whatever generated the file.

Installing Ninja and running a first build

Installation is unusual because there is nothing to install. The README states that installation is not necessary because the only required file is the resulting ninja binary, and that prebuilt binaries for Linux, Mac and Windows are available on the GitHub releases page. Download the binary for your platform, put it somewhere on your PATH, and run `./ninja -h` to see the help output. Optional extras live in misc/: the README notes that Bash completion and the Emacs and Vim editing modes require copying files from that directory to the appropriate locations. To build Ninja from source with the Python generator, run the bootstrap script from the repository root.

./configure.py --bootstrap

The README states that this generates the ninja binary plus a build.ninja file, after which Ninja can build itself. If you have a GoogleTest source directory and want the unit tests, pass its path either as a flag or through an environment variable.

./configure.py --bootstrap --gtest-source-dir=/path/to/googletest
./ninja all
./ninja_test

The CMake route is the alternative when you want to link against a preinstalled GoogleTest instead of building it from source. The README gives this sequence, with test building disabled.

cmake -Bbuild-cmake -DBUILD_TESTING=OFF
cmake --build build-cmake

The resulting binary lands in build-cmake, and the directory name is yours to choose. Omit -DBUILD_TESTING=OFF and the build also produces build-cmake/ninja_test, which the README says is how you run the unit test suite. For the manual itself, the README requires asciidoc and xsltproc on your PATH, then two commands: `./configure.py` followed by `ninja manual doc/manual.html`, which writes doc/manual.html. The PDF variant needs dblatex on your PATH and the target `ninja doc/manual.pdf`.

Where Ninja is the wrong tool

The build file format is the limitation, and it is deliberate. Ninja has no conditionals, no functions and no pattern rules in the sense Make users expect. The README does not document the format at all; it sends you to the manual or to doc/manual.asciidoc. If your build logic depends on branching over platform, compiler or feature detection, that logic has to live in the generator, which means adding a generator to a project that previously needed none. That is a real cost, and it is the reason Ninja is a poor fit for small projects where a Makefile is already readable and fast enough. There is a second boundary in the README itself: Ninja is a standalone executable, not a library, and the Doxygen documentation is described as internal with no public API. Any plan that involves calling into Ninja from another program, or replacing the binary with your own linked copy, runs against the stated design. The README also does not document rollback or downgrade behaviour, so nothing in the repository supports a claim about reverting to an earlier release if a build breaks after an upgrade.

Ninja versus Make, and versus a generator

The honest comparison is not Ninja against Make as two ways to write a build file. It is Ninja against Make as two ways to execute one. Make is both the description language and the executor, and that is why a Makefile can be self-contained and why it becomes hard to reason about at scale. Ninja splits the two roles and optimises only the second. The practical difference shows up in what you maintain: with Ninja you maintain a generator configuration, and build.ninja is a build artifact you should not edit, because the next regeneration overwrites it. With Make you maintain the Makefile itself. If you already use CMake or Meson, that generator is present whether or not Ninja is, so adding Ninja costs you a binary and nothing else. If you do not, Ninja asks you to adopt a generator before it gives you anything. That is the trade, and it is worth stating plainly rather than treating Ninja as a drop-in Make replacement.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-20, so the project is being worked on. Releases are tagged rather than continuous: v1.13.0, v1.13.1 and v1.13.2 are the recent ones, the latest dated 2025-11-20. The README does not describe a support window or a compatibility policy for the build file format, so if you pin a version, pin it explicitly and read the release notes for the tag you choose; the repository does not say what changes between them. Upgrade cost is low for the binary itself, since there is nothing to install and no library to relink, but it is not zero for your build graph, because a generator may emit syntax that a given Ninja version does not accept. The licence is Apache-2.0, which is a permissive licence with an explicit patent grant and a requirement to preserve notices; that is a general description of the licence text, not legal advice, and if you redistribute the binary you should read COPYING in the repository rather than relying on this summary.

Editorial conclusion

Adopt Ninja if a generator such as CMake or Meson is already producing your build graph and you want the executor to be small and fast; the binary is the only required file, so there is nothing to deploy alongside it. Do not adopt it as a hand-written replacement for Make in a small project, because the file format gives you no conditionals, no functions and no built-in rules, and the README points you at the manual for everything beyond the basics. Before committing, check that your generator emits build.ninja with the feature set you need, and verify which release tag you are pinning, since the README does not document an upgrade or rollback path.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. ninja-build/ninja on GitHub
3. Project website
4. README
5. Releases