# Bullet3 splits into a C++ SDK, PyBullet and a vcpkg port that moves on its own

> Bullet Physics SDK is a C++ collision and dynamics library with a Python layer the maintainers push you toward; the build story depends on your platform, and the tagged releases on GitHub stop in 2022 while master keeps moving.

**bulletphysics/bullet3** — Bullet Physics SDK: real-time collision detection and multi-physics simulation for VR, games, visual effects, robotics, machine learning etc.

- Repository: https://github.com/bulletphysics/bullet3
- Website: http://bulletphysics.org
- Stars: 14,812 · Forks: 3,099
- Language: C++
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/bulletphysics-bullet3

## The repository is the C++ source, not the Python package

bullet3 is the official C++ source repository of the Bullet Physics SDK, a library for real-time collision detection and multi-physics simulation aimed at VR, games, visual effects, robotics and machine learning. The Python module is generated from this tree, not the other way round.

What sits in the repository reflects that. src/ is the library, examples/ holds the demo applications including ExampleBrowser, ExampleRobotics and HelloWorld, test/ is the unit test suite, docs/ is documentation, Extras/ holds the bindings including LuaDemo, and build3/ carries the premake scripts and Visual Studio project files. CMakeLists.txt, UseBullet.cmake and BulletConfig.cmake.in are the CMake packaging pieces, so a C++ consumer can find_package-style integration rather than dropping source files into a project.

The first line of advice in the README is that PyBullet bindings are highly recommended for robotics, reinforcement learning and VR, for improved support. That is the maintainers telling you which surface they can actually help with.

## pip3 install pybullet is the whole install for Python work

For Python users the install is one command, and the three commands after it are the sanity check: they run a TensorForce Ant environment, a harder HumanoidFlagrun environment and a DeepMimic test script.

```bash
pip3 install pybullet --upgrade --user
python3 -m pybullet_envs.examples.enjoy_TF_AntBulletEnv_v0_2017may
python3 -m pybullet_envs.examples.enjoy_TF_HumanoidFlagrunHarderBulletEnv_v1_2017jul
python3 -m pybullet_envs.deep_mimic.testrl --arg_file run_humanoid3d_backflip_args.txt
```

If those run, your wheel is working, including the compiled extension. requirements.txt lists numpy as the only Python dependency, and pyproject.toml declares setuptools 42.0.0 or newer as the build requirement, which tells you the package is a compiled extension rather than pure Python.

The README also points to a PyBullet Quickstart Guide hosted as a Google document, and to the forums at bulletphysics.github.io. Documentation is split between the repository docs/ folder, that hosted guide and the forum archives, so expect to move between three places.

## Connecting Python to a running C++ simulation over shared memory

The architecture that matters for robotics work is that Python does not have to own the simulation. A C++ process can run the physics and expose it, and the Python side attaches.

```python
import pybullet as p
p.connect(p.SHARED_MEMORY) #or (p.TCP, "localhost", 6667) or (p.UDP, "192.168.86.10",1234)
```

Three transports in one line: shared memory on one machine, TCP to a port on another, or UDP. The VR sandbox project App_SharedMemoryPhysics_VR is the documented example, and the README says to build it in Release or optimized mode. That split, native C++ for the solver and Python for scripting and learning, is why the project recommends PyBullet rather than a standalone Python physics implementation.

It also explains the build emphasis below: to use any of this from Python, the module has to be built and installed locally.

## Four different build paths, and Linux has one rule

The C++ build is documented four times over, which is itself a fact about the project.

vcpkg is the shortest route on any platform the port supports.

```bash
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install bullet3
```

The README states the port is kept current by Microsoft team members and community contributors, and asks you to file an issue on the vcpkg repository if the version is out of date. That is an unusual arrangement worth knowing: your upgrade path can move through a different project's release cycle.

For CMake on Linux and macOS, the script is the entry point.

```bash
./build_cmake_pybullet_double.sh
```

It invokes cmake and builds into the build_cmake directory, leaving pybullet in Bullet/examples/pybullet and the BulletExampleBrowser binary in Bullet/examples/ExampleBrowser.

Premake is the third path, with per-platform executables in build3.

```bash
cd build3
./premake4_linux --double gmake
./premake4_linux64 --double gmake
./premake4_osx --double --enable_pybullet gmake
```

The constraint that bites: on Linux you must use cmake to build pybullet, because the compiler has issues mixing shared and static libraries. On macOS the Xcode path is build3/xcode4.command, or ./premake_osx xcode4 in a terminal. Windows uses build_visual_studio_vr_pybullet_double.bat and a Visual Studio solution under build3/vs2010.

## ExampleBrowser takes a small set of command line flags

The demo executable in the bin folder accepts a handful of options, which is the whole runtime surface the README documents for the C++ side.

```
[--start_demo_name="Demo Name"]     Start with a selected demo
[--mp4=moviename.mp4]               Create a mp4 movie of the window, requires ffmpeg installed
[--mouse_move_multiplier=0.400000]  Set the mouse move sensitivity
[--fixed_timestep= 0.0]             Use either a real-time delta time (0.0) or a fixed step size (0.016666)
```

The fixed timestep choice is the one with real consequences. Real-time delta time varies with elapsed time, while a fixed step sets a constant simulation interval. Which one you use determines whether two runs of the same scene produce the same trajectory, and for reinforcement learning that is not a cosmetic setting.

Recording to mp4 needs ffmpeg installed on the machine. Mouse picking grabs objects, ALT or CONTROL switches to Maya style camera controls, F1 creates a series of screenshots and ESCAPE exits.

## Where Bullet is the wrong choice

The README closes the issue tracker: it says the tracker was flooded with support questions and is closed until it is cleaned up, pointing people at the PyBullet forums instead. For a library you plan to depend on for years, support arriving as forum threads rather than tickets is a real cost, and there is no date for reopening.

The OpenCL GPU path is where the documentation warns you off. The README states the entire collision detection and rigid body dynamics can be executed on the GPU, but it also states the software does not work on OpenCL CPU devices, that a laptop GPU will probably be slow, and that an OpenCL driver often fails to compile a kernel. It asks for a high-end desktop GPU such as an AMD Radeon 7970 or an NVIDIA GTX 680 or better, and admits more work is required to cover all OpenCL kernels. Treat that path as experimental and validate it on your own hardware before designing around it.

There is also no versioning discipline you can lean on from the tags alone, and for a robotics deployment the portability story is the compiler: a C++ 2003 compiler, tested on Windows, Linux, Mac OSX, iOS and Android, with OpenGL 2 or 3 needed only for the graphical demos.

## Conclusion

Adopt PyBullet rather than the raw C++ library if your work is robotics, reinforcement learning or VR, since that is the binding the maintainers recommend and the one their examples and quickstart cover. Stay on the C++ SDK when you are shipping a game or a real-time effect and need the build tuned yourself. Verify first which artifact your team actually consumes: master was last pushed on 2026-10-09, yet the newest GitHub release tag is 3.25 from 2022-04-24, so a version number alone will not tell your users what they have. Confirm that pip install pybullet resolves the build you expect, that the vcpkg bullet3 port is current if you use it, and that any OpenCL path you need still runs on your hardware, since the README calls OpenCL support experimental and excludes OpenCL CPU devices.

## FAQ

### How do I install PyBullet?

Run pip3 install pybullet --upgrade --user, then run one of the example modules such as pybullet_envs.examples.enjoy_TF_AntBulletEnv_v0_2017may to confirm the compiled extension works. numpy is the only listed Python dependency.

### How do I build Bullet with PyBullet on Linux?

The README says on Linux you need cmake to build pybullet, because the compiler has issues mixing shared and static libraries. Run ./build_cmake_pybullet_double.sh, which builds into the build_cmake directory and leaves pybullet in Bullet/examples/pybullet.

### Can I install Bullet through vcpkg?

Yes. Bootstrap vcpkg, run ./vcpkg integrate install and then ./vcpkg install bullet3. The README notes the port is maintained by Microsoft team members and community contributors and asks for an issue on the vcpkg repository if it falls out of date.

### How do I connect PyBullet to a C++ simulation running separately?

Call p.connect with p.SHARED_MEMORY for a local process, or p.TCP with a host and port such as localhost and 6667, or p.UDP. The App_SharedMemoryPhysics_VR project is the documented example and should be built in Release mode.

### Does Bullet support OpenCL on the CPU?

No. The README states the software currently does not work on OpenCL CPU devices, warns that laptop GPU performance will not be good, and notes that OpenCL drivers often fail to compile a kernel. It asks for a high-end desktop GPU.

## Sources

- [bulletphysics/bullet3 on GitHub](https://github.com/bulletphysics/bullet3)
- [Issues](https://github.com/bulletphysics/bullet3/issues)
- [Project website](http://bulletphysics.org)
- [README](https://github.com/bulletphysics/bullet3/blob/master/README.md)
- [Releases](https://github.com/bulletphysics/bullet3/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bulletphysics-bullet3