PythonRobotics: A Readable Algorithm Library and Textbook for Robotics Engineers

A Readable Algorithm Collection for Robotics Study

PythonRobotics is described in the repository as both a Python code collection and a textbook of robotics algorithms. The design priorities are stated in the README: algorithms should be easy to read for understanding basic ideas, they should be widely used and practical, and dependencies should be minimal.

This is not a production robotics framework. It does not provide a hardware abstraction layer, a ROS integration, or a real-time control loop. Each script in the repository is a self-contained simulation of one algorithm, intended to be read and run to observe the algorithm's behavior. The target audience is students learning robotics from first principles, researchers who want a quick reference implementation of a classical method, and engineers evaluating whether a given algorithm fits their problem before writing a production version.

An academic paper covering the project is available at arXiv (arXiv:1808.10703), and an online textbook with mathematical background for each algorithm is hosted at atsushisakai.github.io/PythonRobotics. The README points to both as the primary reference material beyond what the code itself shows.

Repository Organization: Seven Algorithm Categories

The repository is organized into seven top-level directories, each corresponding to a category of robotics problem.

Localization contains three approaches: Extended Kalman Filter (EKF) localization, particle filter localization, and histogram filter localization. The EKF module uses a landmark-based sensor model; the particle filter simulation shows true trajectory, dead reckoning, and estimated trajectory with RFID distance measurements. The histogram filter example treats position as a 2D probability grid with known yaw.

Mapping covers Gaussian grid maps, ray casting grid maps, lidar-to-grid conversion, k-means object clustering, and rectangle fitting.

SLAM provides Iterative Closest Point (ICP) matching and FastSLAM 1.0 implementations.

PathPlanning is the largest category. It includes the Dynamic Window Approach, grid-based search (Dijkstra, A*, D*, D* Lite, Potential Field, and coverage planning), Particle Swarm Optimization, state lattice planning (biased polar and lane sampling), Probabilistic Road-Map (PRM), Rapidly-Exploring Random Trees in several variants (RRT, RRT*, RRT* with Reeds-Shepp, LQR-RRT*), quintic polynomial planning, Reeds-Shepp planning, LQR path planning, and optimal trajectory in a Frenet frame.

PathTracking includes move-to-pose control, Stanley control, rear wheel feedback, LQR speed and steering control, model predictive speed and steering control, and nonlinear model predictive control with C-GMRES.

ArmNavigation covers N-joint arm point control and obstacle avoidance for arms.

AerialNavigation and Bipedal round out the collection with drone 3D trajectory following, rocket-powered landing, and a bipedal planner using an inverted pendulum model.

Requirements and Getting Started

PythonRobotics requires Python 3.13.x. The runtime dependencies are NumPy, SciPy, Matplotlib, and cvxpy. Development dependencies add pytest and pytest-xdist for testing, mypy for type checking, sphinx for documentation generation, and pycodestyle for style checks.

The README gives three setup steps. First, clone the repository:

git clone https://github.com/AtsushiSakai/PythonRobotics.git

Second, install the required libraries. Using conda:

conda env create -f requirements/environment.yml

Or using pip:

pip install -r requirements/requirements.txt

Third, run a Python script from inside the relevant subdirectory. Each subdirectory is self-contained; there is no single entry point for the full collection. To see the EKF localization simulation, for example, navigate into the Localization directory and execute the corresponding script. Matplotlib will render an animation showing the filter's output.

The repository includes a runtests.sh script and a tests/ directory. The CI configuration uses CircleCI (via .circleci/) and AppVeyor. A ruff.toml and mypy.ini are present for linting and type checking.

Path Planning Coverage: From Classical Search to Sampling-Based Methods

The PathPlanning category is the deepest part of the repository. It separates grid-based deterministic search from sampling-based probabilistic methods, which reflects a real division in the robotics planning literature.

On the deterministic side, Dijkstra and A* represent the standard graph-search baseline. D* and D* Lite add incremental replanning, which is useful when the environment changes during navigation. The Potential Field approach models the goal as an attractor and obstacles as repellers; the README notes this is susceptible to local minima, which is a real limitation that makes it unsuitable for complex cluttered environments without augmentation.

The sampling-based methods include PRM and several RRT variants. RRT* is the asymptotically optimal version of RRT that rewires the tree as new samples arrive. The LQR-RRT* variant integrates a linear-quadratic regulator for trajectory smoothing. The Reeds-Shepp path planner handles the geometry of car-like robots that can move both forward and backward.

The PathTracking directory addresses the separate problem of following a planned path with a real vehicle model. Stanley control and LQR speed and steering control are standard approaches for autonomous vehicle lateral control. The model predictive control implementation uses cvxpy to set up and solve the optimization problem at each step.

All of these run as 2D (or in some cases 3D) simulations. The README does not describe any mechanism for running them against a physical robot or interfacing them with a hardware abstraction layer.

Where PythonRobotics Is the Wrong Tool

PythonRobotics makes specific trade-offs that rule it out for certain use cases.

The first limitation is that every script is a simulation. There is no documented interface to physical hardware, no ROS node wrapper, and no sensor abstraction layer. An engineer who wants to deploy an EKF onto a real mobile robot will need to re-implement the algorithm against their actual sensor API; PythonRobotics gives them a readable reference, not a deployable module.

The second limitation is the Python 3.13.x requirement. Scripts that use cvxpy in particular depend on a working numerical solver installation, which can be non-trivial in embedded or containerized environments. The requirement file pins specific library versions, but the README does not document how to handle version conflicts in environments where other Python packages are already installed.

The third limitation is coverage depth. The repository covers each algorithm at a demonstration level. FastSLAM 1.0 is present, but FastSLAM 2.0 is not. The particle filter uses RFID landmarks; lidar-based variants are not documented. Engineers who need a production-quality or research-quality implementation of a specific algorithm will need to extend or replace what is here.

The LICENSE file is present in the repository but its contents are not reproduced in the README excerpt provided. The arXiv paper citation in the README asks users to cite it when using the code in published research.

PythonRobotics Versus the Robotics Toolbox for Python

Search traffic alongside PythonRobotics includes the phrase "not your grandmother's toolbox the robotics toolbox reinvented for python," which is the subtitle of Peter Corke's Robotics Toolbox for Python. The two projects take different approaches to the same general problem.

PythonRobotics organizes its content by algorithm category. Each algorithm lives in its own directory as a standalone script designed for reading. There is no unified object model, no robot description format, and no common interface across algorithms. The goal is transparency: a student should be able to open one file and follow the logic without importing a framework.

The Robotics Toolbox for Python, by contrast, builds around a common robot model and supports kinematic and dynamic simulation with a shared API. That architecture makes it easier to compose components but adds a learning curve for the framework itself.

The difference in approach is practical for the target audience. PythonRobotics is most useful when the goal is to understand a specific algorithm in isolation. A project that needs to chain localization, mapping, and path planning together as a system is asking for something PythonRobotics was not designed to provide.

Editorial conclusion

PythonRobotics is the right starting point for students and researchers who need readable, self-contained Python implementations of classical robotics algorithms to study or adapt. It covers localization, SLAM, path planning, path tracking, arm navigation, aerial navigation, and bipedal balance in a single repository. It is the wrong tool for anyone building production software for a physical robot: the README describes simulation code with no hardware abstraction layer or ROS integration documented. Verify that the specific algorithm you need, such as D* Lite or LQR-RRT*, is present in the relevant subdirectory before committing to the repository as a reference.

Frequently asked questions

Official sources

1. AtsushiSakai/PythonRobotics on GitHub
2. Issues
3. Project website
4. README