txoof/install_pybullet.md

## install_pybullet.md

      
    Raw
  

              install_pybullet.md
            
          
    Installing PyBullet on macOS Sequoia (15.x) with Apple Silicon

TL;DR

PyBullet fails to install on macOS Sequoia due to C++ compiler incompatibilities. Install an older LLVM compiler via Homebrew and use it to build pybullet:
brew install llvm@16
export PATH="/opt/homebrew/opt/llvm@16/bin:$PATH"
export CC="/opt/homebrew/opt/llvm@16/bin/clang"
export CXX="/opt/homebrew/opt/llvm@16/bin/clang++"
pip install pybullet --break-system-packages

The Problem

When attempting to install pybullet via pip on macOS Sequoia (15.x), the installation fails during the compilation phase with errors like:
fatal error: 'new' file not found
fatal error: 'algorithm' file not found
fatal error: 'iostream' file not found

The build process fails when trying to compile C++ source files. The compiler cannot locate standard C++ library headers. This happens even with:

Latest Xcode Command Line Tools installed
Properly configured SDK paths
Valid compiler toolchain

Affected Systems


macOS Sequoia 15.x
Apple Silicon Macs (M1, M2, M3, M4)
Apple Clang version 17.x
Python 3.10+


Prerequisites: Installing Homebrew

If you don't have Homebrew installed, you'll need it to get the older LLVM compiler.
Install Homebrew

Run this command in Terminal:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
After Installation

Follow the post-installation instructions to add Homebrew to your PATH. Typically you'll need to run:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
Verify installation:
brew --version
Resources:

Official Homebrew website: https://brew.sh
Homebrew documentation: https://docs.brew.sh


The Solution

Step 1: Install LLVM 16 via Homebrew

brew install llvm@16
This installs an older version of the LLVM compiler toolchain that successfully compiles pybullet.
Step 2: Configure Environment Variables

Set these environment variables to tell pip to use the LLVM 16 compiler:
export PATH="/opt/homebrew/opt/llvm@16/bin:$PATH"
export CC="/opt/homebrew/opt/llvm@16/bin/clang"
export CXX="/opt/homebrew/opt/llvm@16/bin/clang++"
Note: These exports only last for your current terminal session. If you open a new terminal, you'll need to set them again.
Step 3: Install PyBullet

pip install pybullet --break-system-packages
Or if you're using a virtual environment:
# Activate your virtual environment first
source venv/bin/activate

# Then install
pip install pybullet
Step 4: Verify Installation

Test that pybullet installed correctly:
python -c "import pybullet; print(pybullet.__version__)"
You should see the version number (e.g., 3.2.7) printed without errors.

Troubleshooting

"Command not found: brew"

Homebrew isn't in your PATH. Run:
eval "$(/opt/homebrew/bin/brew shellenv)"
Then try the brew install command again.
Still Getting Compilation Errors After Following All Steps

Double-check that the environment variables are set correctly in your current terminal:
echo $CC
echo $CXX
These should show the paths to the LLVM 16 clang compilers.
If they're empty or showing different paths, re-run the export commands from Step 2.
Need to Use the Fix Permanently?

If you frequently need to install packages that require compilation, you can add the environment variables to your shell profile.
For zsh (default on macOS):
echo 'export PATH="/opt/homebrew/opt/llvm@16/bin:$PATH"' >> ~/.zshrc
echo 'export CC="/opt/homebrew/opt/llvm@16/bin/clang"' >> ~/.zshrc
echo 'export CXX="/opt/homebrew/opt/llvm@16/bin/clang++"' >> ~/.zshrc
For bash:
echo 'export PATH="/opt/homebrew/opt/llvm@16/bin:$PATH"' >> ~/.bash_profile
echo 'export CC="/opt/homebrew/opt/llvm@16/bin/clang"' >> ~/.bash_profile
echo 'export CXX="/opt/homebrew/opt/llvm@16/bin/clang++"' >> ~/.bash_profile
Warning: This will make LLVM 16 the default compiler for all C/C++ compilation on your system. Only do this if you understand the implications.

Related Issues and Resources

GitHub Issues


bullet3#4712 - Failed building wheel for pybullet (macOS Sequoia)
bullet3#4607 - Clang 18 compilation issues with outdated zlib

Official Resources


PyBullet Quickstart: https://docs.google.com/document/d/10sXEhzFRSnvFcl3XxNGhnD4N2SedqwdAvK3dsihxVUA/edit
Bullet Physics: https://pybullet.org/wordpress/
PyPI Package: https://pypi.org/project/pybullet/


Contributing

If this gist helped you, please share it with others facing the same issue!
Last updated: November 2025

Tested on: macOS Sequoia 15.6, Apple Silicon M-series

Python version: 3.10
No results found