learnsyslab/gym-pybullet-drones

gym‑pybullet‑drones – A Gym‑compatible quadcopter simulator

What it is

• A lightweight Python package that wraps the PyBullet physics engine to provide a Gymnasium (the successor of OpenAI Gym) environment for single‑ and multi‑drone control.
• Targets research on reinforcement learning, classic control, and system identification for quadrotors.
• Includes ready‑to‑run examples for PID control, downwash modelling, and RL training with Stable‑Baselines3 2.0 (PPO).
• Offers an optional Betaflight SITL integration so the same environment can be driven by a real‑world flight‑stack in simulation.

Key components

• gym_pybullet_drones package containing the core Aviary classes that define the drone dynamics, observation space, and reward functions.
• Example scripts (pid.py, pid_velocity.py, mrac.py, downwash.py, learn.py, play.py, beta.py) that demonstrate:
  • classic controllers (PID, MRAC),
  • aerodynamic downwash effects between drones,
  • single‑agent and multi‑agent RL training/evaluation,
  • interfacing with Betaflight SITL.
• Test suite (pytest tests/) to verify environment correctness.
• Compatibility layer for Gymnasium and Stable‑Baselines3 2.0, making it easy to plug into modern RL pipelines.

Installation (conda‑based, works on Ubuntu 24.04 and macOS 26)

git clone https://github.com/learnsyslab/gym-pybullet-drones.git
cd gym-pybullet-drones

conda create -n drones python=3.12
conda activate drones

# Build pybullet from source (required for Python >3.10)
sudo apt install build-essential          # Ubuntu only
# macOS: CFLAGS="-Dfdopen=fdopen" pip install pybullet --no-cache-dir
pip install -e .

The README notes that on macOS you may need the CFLAGS hack; on Ubuntu you must have a C compiler for the pybullet build.

Running the examples

# Classic control demos
cd gym_pybullet_drones/examples
python pid.py
python pid_velocity.py
python mrac.py

# Downwash (air‑flow interaction) demo
python downwash.py

# Reinforcement‑learning (single‑drone hover)
python learn.py               # trains PPO
python play.py --model_path results/<latest>/best_model.zip

# Multi‑drone RL (two drones hover at different heights)
python learn.py --multiagent true
python play.py --multiagent true --model_path results/<latest>/best_model.zip

For the Betaflight software‑in‑the‑loop demo (Ubuntu only):

./gym_pybullet_drones/assets/clone_bfs.sh 2   # builds two Betaflight SITL binaries
cd gym_pybullet_drones/examples
python beta.py --num_drones 2

What you can use it for

• Benchmarking new RL algorithms on a physics‑accurate quadrotor model.
• Studying multi‑agent coordination, downwash, and formation flight.
• Comparing classic controllers against learned policies in a common simulation.
• Rapid prototyping before moving to hardware (the Betaflight SITL bridge mimics a real flight stack).

Citation If the code contributes to a publication, cite the original IROS 2021 paper:

@INPROCEEDINGS{panerati2021learning,
  title={Learning to Fly---a Gym Environment with PyBullet Physics for Reinforcement Learning of Multi-agent Quadcopter Control},
  author={Jacopo Panerati and Hehui Zheng and SiQi Zhou and James Xu and Amanda Prorok and Angela P. Schoellig},
  booktitle={2021 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},
  year={2021},
  pages={7512-7519},
  doi={10.1109/IROS51168.2021.9635857}
}

Related projects (mentioned in the README)

• safe-control-gym – for symbolic dynamics and safety‑constrained control.
• crazyflow – JAX‑based, differentiable simulation.
• aerial-autonomy-stack – full PX4/ArduPilot + ROS2 + JetPack deployment.

Bottom line gym-pybullet-drones is a functional, research‑grade simulation environment that bridges classic control, reinforcement learning, and real‑world flight‑stack testing for quadrotors. It is actively maintained (featured in GitHub’s Maintainer Spotlight 2026) and provides clear installation and example scripts, making it a solid starting point for anyone exploring AI‑driven aerial robotics.