toppra: time-optimal path parameterization for constrained robot motion

The problem is timing, not geometry

Motion planning produces a geometric path. What it does not produce is a schedule for following it. toppra addresses exactly that gap. It is described as a library for computing the time-optimal path parameterization for robots subject to kinematic and dynamic constraints, and the inputs are two things: a geometric path p(s) with s in [0, s_end], and a list of constraints on quantities such as joint velocity, joint acceleration and tool Cartesian velocity.

Given those, toppra returns the time-optimal path parameterization, written as s_dot(s), from which the fastest trajectory q(t) that satisfies the given constraints can be found.

That distinction is what makes the library reusable. A planner may spend most of its time deciding where the robot goes, and then hand the result to a controller that has to decide how fast. The second decision is a constrained optimisation in its own right, and it is where a naive profile generator either wastes time or violates a limit. The target audience is therefore robotics engineers working on trajectory generation and control, not people looking for a planner.

Constraints are the input, so the library is a constraint toolkit

Because the constraint list is an input rather than a fixed setting, toppra is best understood as machinery for applying constraints to a path rather than as a fixed algorithm. The documented examples reflect that. The examples directory holds plot_kinematics.py, plot_kinematics_duration.py, plot_robust_kinematics.py, plot_scalar_example.py and plot_straight_line.py, which tells you the shape of the API surface: you build constraints, then ask for the parameterization.

The names also point at a distinction the library makes. The kinematics example is the ordinary case where the limit is a function of the configuration. The robust kinematics example suggests the harder case where the bound does not depend on position alone, and the duration example shows that the output can also be expressed as a total time rather than only as s_dot(s). The scalar example appears to work with a single scalar constraint.

One caveat on scope: the documentation and tutorials live on a hosted documentation site rather than in the repository, so the details of the constraint classes and the numerical scheme behind the optimization are not visible from the repository alone. If your work depends on which solver is used or how the bound is discretized, that site is where you have to go, and the paper is the other reference: the project asks users doing research to cite the accompanying IEEE Transactions on Robotics paper, A new approach to Time-Optimal Path Parameterization based on Reachability Analysis, volume 34 issue 3, pages 645 to 659, 2018.

Installing the package and running the tests

Installation from PyPI is one command:

pip install toppra

For development from source, the repository documents the editable install of the python subdirectory:

pip install -e python

The layout explains that path. The tree has separate cpp/ and python/ directories, with the C++ side carrying the implementation and the Python side exposing it. Build and release tooling sits alongside them: a Makefile, tasks.py for the invoke-style task runner, tox.ini, pytest.ini, mypy.ini and .pylintrc for the Python side, and dockerfiles/ for building the C++ part in a container.

The Makefile shows how the project checks itself, and the coverage target is a plain pytest invocation:

python -m pytest -q --cov-report term --cov-report xml --cov=toppra tests

There is also a lint target that runs pylint with .pylintrc, then pycodestyle with a maximum line length of 120 ignoring E731 and W503, then pydocstyle, and a DOC target that builds the HTML documentation with sphinx-build into docs/build. The presence of a coverage target, a docs target and a publish target that runs twine upload after python setup.py sdist tells you the project still has a complete release workflow, even though the tagged releases are old.

Python support is on its way out

The single most important line for an adopter is the note at the top of the README: Python support for the library will be dropped, and the advice is to consider using the C++ version with bindings instead.

Read that alongside the release history and the picture becomes clear. The tagged releases are old: v0.3.1 from 2020-08-23, v0.3.0 from 2020-05-03 with a brand new C++ API and improvements to the Python API, and v0.2.2 from 2019-04-27 with improved Python 3 support. The repository is not archived and the last push was on 2026-10-19, so work continues on the default branch develop, but the published versions on the index have not moved in years.

The credits section explains the shape of the project. It was developed by Hung Pham and Pham Quang Cuong at Eureka Robotics, formerly CRI Group, with a listed C++ API contribution from Joseph Mirabel, Python 3 support from EdsterG, and ROS support and maintenance from Sebastian Castro. That last credit is worth noting: ROS support was contributed and maintained by someone other than the original authors, which is the kind of arrangement that tends to fade when a project changes direction, and the direction here is documented explicitly.

The practical consequence is that a new Python user is joining a shrinking surface. If your controller is Python today, you are writing code against an API the maintainers have said will be removed, and the upgrade path is a C++ binding rather than a version bump.

Where the library is the wrong choice

There are two clear boundaries. The first is scope. toppra times a path you already have. If you need the path itself, or you need collision avoidance, or you need the trajectory to be globally optimal in space rather than in time along a given curve, this is the wrong library and no configuration setting will change that.

The second is the language boundary described above. The Python path is scheduled for removal, and the C++ path means compiling, bindings and a build that involves dockerfiles/ for the native part. A team without C++ in its stack, or a team that needs the parameterization inside a Python research codebase where the surrounding tooling is pandas and matplotlib, is being asked to change more than a dependency.

The numerical side has its own honest limits. The algorithm targets the time-optimal parameterization under the constraints you hand it, and the standard formulation requires those constraints to be evaluated over the path. A badly chosen constraint, a path parameterisation that is degenerate near s_end, or a constraint that cannot be satisfied along the whole path will produce output that is optimal for a problem you did not quite mean to pose. The documentation examples are the reference for how a constraint should be built, and reading plot_robust_kinematics.py is a reasonable way to see what a non-trivial constraint looks like in practice.

Licence, citation and what a fork would cost

The licence is MIT, so the code can be read, modified, vendored and shipped without the obligations that come with copyleft, and the repository keeps a LICENSE file plus a HISTORY.md changelog. The project also asks that users doing research cite the 2018 IEEE Transactions on Robotics paper and put a star on the repository.

The licensing question that matters more is a practical one rather than a legal one. If you need the library in Python and the Python API is going away, your options are to bind the C++ implementation yourself, to keep a fork of the Python package and own the maintenance, or to pick a different approach. A fork is cheap in the MIT sense and expensive in the engineering sense, because a time-optimal parameterization is the kind of numerical code where correctness depends on careful review rather than on a quick patch.

There is also a versioning tool in the tree, .bumpversion.cfg, which suggests the release numbering is handled automatically, and the publish target in the Makefile uploads to PyPI with twine. So if you are maintaining a fork, publishing under your own name is mechanically straightforward. What that does not give you is the upstream fix stream, because upstream is moving toward C++.

Editorial conclusion

Adopt toppra if your stack already produces geometric paths and needs the fastest admissible timing for them, and if you are prepared to target the C++ API. Skip it if you need a maintained Python library, since the project states that Python support will be dropped, or if you need path generation rather than path timing. Verify first that your constraint types are among those the library covers, joint velocity, joint acceleration and tool Cartesian velocity among them, before writing the controller that consumes the returned s_dot(s).

Frequently asked questions

Official sources

1. hungpham2511/toppra on GitHub
2. License: MIT
3. Project website
4. README
5. Releases