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

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.

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.

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.

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.

./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.

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.

Editorial 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.

Frequently asked questions

Official sources

1. bulletphysics/bullet3 on GitHub
2. Issues
3. Project website
4. README
5. Releases