Guide · Open source

How to use Box2D: install, build and run your first physics world

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Box2D is a 2D physics engine for games. It works out how shapes move, collide, slide and rotate, so your game does not have to write that math from scratch. This guide walks through cloning and building the project, creating a physics world, and using the replay viewer, so you can start simulating bodies in your own code.

Box2Derincatto/box2d · ★ 10.5k · MIT Install options & downloads

Quick start

1Clone the repository. Run git clone https://github.com/erincatto/box2d to get the source.
2Configure with a preset. Run cmake --preset linux-release, or the windows or macos preset for your platform.
3Build. Run cmake --build --preset linux-release and find the output in the build sub-folder.
4Create a world. Call b2DefaultWorldDef, set gravity, then b2CreateWorld in your language of choice.
5Step the simulation. Call b2World_Step once per frame with a time step and sub-step count, then read back body positions.
6Open a replay. Pass a .b2rec file to the samples program to view a recording.

What Box2D does and who it is for

Box2D calculates how 2D shapes move and interact. You add bodies and shapes to a world, step the simulation each frame, and read back positions. It is written in portable C17 and covers collision detection, joints and character movement in two dimensions.

It suits game developers building 2D games who want a ready-made physics solver, developers working in C or in languages that can call C, and projects with many bodies that need good performance. It is not a fit for 3D physics or for anyone who needs a visual, drag-and-drop editor.

Good fit: 2D games, C or C-callable languages such as Zig and Swift, large numbers of bodies, deterministic simulation, replay and snapshot and restore.
Not a fit: 3D physics, visual editors, or contributing code directly via pull requests (the README asks you to file issues instead).

Install prerequisites: CMake, git and a C17 compiler

You need CMake and git on your PATH. You also need a compiler that supports C17 to build the library. The presets use the default native toolchain: Visual Studio on Windows, Make on Linux and Xcode on macOS. No specific compiler version is required.

Install CMake from cmake.org.
Install git from git-scm.com.
Windows: install Visual Studio. Linux: Make. macOS: Xcode.

Clone and build with CMake presets

The presets in CMakePresets.json give one build flow on every platform. Visual Studio, VS Code and CLion pick them up automatically: open the folder and choose a preset. From the command line, clone the repository, configure, then build. The example below uses the Linux preset; Windows uses the windows preset and macOS uses the macos preset.

Use the *-debug build presets for a debug build. The README says this is not recommended for the replay viewer.
Results are in the build sub-folder.

git clone https://github.com/erincatto/box2d
cmake --preset linux-release
cmake --build --preset linux-release

Create your first physics world in code

Box2D is driven by code, not a visual tool. The Zig example below creates a world with downward gravity, then steps it at 60 frames per second with 4 sub-steps. Destroy the world when you are finished with it. The Swift package exposes the same C API, with structs passed as inout arguments using &.

Set gravity through the world definition, here world_def.gravity.y = -10.0.
Call the step function once per frame with a time step and sub-step count.
In Zig, fetch the dependency with zig fetch --save git+https://github.com/erincatto/box2d and link it in build.zig.

const box2d = @import("box2d");

pub fn main() void {
    var world_def = box2d.b2DefaultWorldDef();
    world_def.gravity.y = -10.0;
    const world_id = box2d.b2CreateWorld(&world_def);
    defer box2d.b2DestroyWorld(world_id);

    box2d.b2World_Step(world_id, 1.0 / 60.0, 4);
}

Use Swift Package Manager or install the library

For Swift, add the repository as a package dependency in Package.swift with branch main, then add the box2d product to your target. To install the library system-wide for other C projects, run the build and install steps. Installing also provides a pkg-config file, so you can check the version and get build flags.

Installing may need sudo.
pkg-config --modversion box2d reports the installed version.
pkg-config --cflags --libs box2d gives the build flags.

mkdir build
cd build
cmake ..
cmake --build . --config Release
cmake --install .

Open a recording in the replay viewer

The samples app doubles as a viewer for Box2D recordings, which use the .b2rec extension. Any preset builds it. Pass a recording path on the command line to open it directly. Without an argument, open a recording from the Replay menu. On Windows you can also drag a .b2rec file onto samples.exe. The docs/recording.md file in the repository explains how to make a recording.

Linux: build/bin/samples path/to/session.b2rec
Windows: build\bin\Release\samples.exe path\to\session.b2rec
macOS: build/bin/Release/samples path/to/session.b2rec

Check compatibility and performance options

The library and samples build and run on Windows, Linux and Mac. The library needs a C17 compiler, and the samples need C++20. Box2D uses SSE2, AVX2 and Neon (AArch64) SIMD to speed up math. You can disable this by defining BOX2D_DISABLE_SIMD. SSE2 is used automatically when the CPU does not support AVX2.

What people use it for

Building a 2D platformer with collision, joints and character movement.
Creating a physics sandbox with many bodies that needs good performance.
Making deterministic simulations that can be recorded, replayed or restored from a snapshot.
Adding 2D physics to a Zig or Swift project through its C API.

Frequently asked questions

Is Box2D free to use?

Yes. Box2D uses the MIT license, and the README says it is developed by Erin Catto. Check the LICENSE file in the repository for the full terms before shipping.

What do I need to install Box2D?

You need CMake, git and a compiler that supports C17. The presets use Visual Studio on Windows, Make on Linux and Xcode on macOS.

How do I build Box2D on Linux?

Clone the repository, run cmake --preset linux-release to configure, then cmake --build --preset linux-release to build. Results are in the build sub-folder.

Can Box2D do 3D physics?

No. Box2D is a 2D physics engine only. The README points developers who need a 2D solver to it, and 3D projects need a different engine.

What are the alternatives to Box2D?

Comparable projects named for this item are Chipmunk2D, Box2D Lite and Nape. Compare them on the features you need, such as collision, joints and language support.

Does Box2D have a visual editor?

No. The README describes a code API and sample programs only, so you will set up bodies and shapes in code.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Box2D suits developers building 2D games who want a fast, well-tested solver in C or a C-callable language, and who are comfortable building from source. Pick something else if you need 3D physics, a visual editor, or a tool that asks for no code.

Install options & downloads