Skip to main content

a suite of utility functions to facilitate robotic planning related research on the pybullet physics simulation engine.

Project description

pybullet_planning is a suite of utility functions to facilitate robotic planning related research on the pybullet physics simulation engine. Planning research made easy.

Main features

  • easy-to-use functions to connect with pybullet, tailored for task and motion planning research
  • built-in implementations of standard motion planners, including PRM, RRT, biRRT, A* etc.

Getting Started

pybullet_planning can be installed using pip:

pip install pybullet_planning


On Windows, you may need to install Microsoft Visual C++ 14.0, if pybullet installation fails.

Once the installation is completed, you can verify your setup. Start Python from the command prompt and run the following:

>>> import pybullet_planning as pp

First Steps

Examples can be found at the unit tests. You will be need to install pytest to run these tests (pip install pytest).

Then, individual tests can be run by using their pytest markers by:

pytest -s -m collision_fn --viewer
pytest -s -m motion_planning_2D --viewer

Additional pytest-free examples can be found at pybullet_planning_tutorials.


Check the Contributor’s Guide for more details.


Caelan Reed Garrett. PyBullet Planning. 2020.

This package was initiated and maintained by Caelan Garrett @caelan and other contributors.


This repo is a stable and documented fork of Caelan’s pybullet-planning (previously called ss-pybullet) and motion-planners. New features will continue to be introduced first through these separate repos, and integrated into the current package later.


All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.







Known Unresolved Issues

  • get_body_collision_vertices does not support cloned body now. We don’t have a good way to do catch-throw for this now.
  • Cloning body from an already cloned body introduces unexpected result (visual or collision data erased etc).


Added - Added distance_threshold to pairwise_link_collision_info and pairwise_link_collision to allow collision checking given a penetration threshold - Added sweep_collision_fn to birrt to allow sweep collision check in edge expansion - Added coarse_waypoints to the smooth_path function to give options for use refined shortcut to ensure collision-free results. - LOGGER introduced to replace print - Added get_data_filename_and_height to include cached mesh filename and scale from get_model_info - Added CreateVisualArray and CreateCollisionArray for visual_shape_from_data and visual_shape_from_data. We use the new get_data_filename_and_height when file_name is UNKNOWN_FILE. - Added load_pybullet support for stl files by create_obj. - Added get_body_collision_vertices for getting body collision vertices in its current configuration.

Changed - Apply HideOutput to pybullet IK error printouts in inverse_kinematics_helper - motion_planners module up-to-date with commit e6f23053e. - Changed the mesh reading procedure in vertices_from_data from pp.read_obj to This fixes #9. - smooth_path’s max_iterations argument changed to max_smooth_iterations - ‘set_color’ defaulted to set the color of all the links of body. - vertices_from_data get filename and scale from cached INFO_FROM_BODY (through get_data_filename_and_height) if the data’s filename does not end with .urdf

Fixed - Fixed read_obj returns empty dict if obj file does not start with objects (o object_name) - Fixed get_extend_fn(q1,q2) to include q1 in its output path. This bug was causing incorrect planning result in birrt, because the two trees will have a gap in the middle that is unchecked. - Fixed a minor mesh vertex scaling bug in vertices_from_data - catch get_num_joints(body) == 0 when a rigid body without joint and link are passed to clone_body - clear INFO_FROM_DATA when disconnect or reset_simulation


Added - Added current_conf to as the single-node ladder in the ladder graph Cartesian planning plan_cartesian_motion_lg

Changed - Changed Attachment.from_data to construct parent and child bodies from body name data - Changed EdgeBuilder from using upper_tm and joint_vel_limits to directly using jump_threshold




  • Added SE3 floating body motion planning
  • Added ladder graph cartesian planner


  • Removed requirments.txt, moved dependencies into



  • Fixed Windows OS “Display not in os.environ” issue in connect



  • diagnosis collision checking function to help visualizing the collision bodies’ information
  • add workspace_bodies to the get_collision_fn to check collisions with the obstacles specified in a URDF file.
  • move ik_interface module from application side to this repo, since it’s “universal” for fixed-end robot. Might need to add a separete one for robots with moving base later.
  • enable travis ci unit test, collision_fn well tested
  • get_floating_body_collision_fn to check a body without joints’s collision. Associated test added.
  • Added snap_sols to kinematics.ik_utils


  • add extra_disabled_collisions parameter to get_collision_fn, plan_joint_motion
  • Changed get_name to return name without index if name is not ‘’


  • get_collision_diagnosis_fn removed, integrated into the get_collision_fn


  • utils.numeric_sample.randomize: random.shuffle cannot operate on a range in py 3.x. Enforced conversion to list to fix it.
  • Fixed get_collision_fn to ignore checking between bodies both specified in attachment and obstacles (prioritize its role as attachment)



  • add body name for bodies from create_obj

Requested features

  • clone_body work for bodies from create_obj



  • Initial version
  • Divide the original file into separate modules
  • Modules cycle dependency resolved.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pybullet_planning-0.6.0.tar.gz (411.6 kB view hashes)

Uploaded source

Built Distribution

pybullet_planning-0.6.0-py2.py3-none-any.whl (131.3 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page