stack-of-tasks/pinocchio: rigid body dynamics and analytical derivatives in C++ and Python

What Pinocchio solves, and who ends up using it

Pinocchio targets the arithmetic that sits underneath robot control and simulation code. For a poly-articulated system described by a URDF, SDF or MJCF file, it computes forward kinematics, forward and inverse dynamics, centroidal dynamics, and the analytical derivatives of those quantities. The README states that the library builds on and revisits the algorithms introduced by Roy Featherstone, and that it provides derivatives of the Recursive Newton-Euler Algorithm and the Articulated-Body Algorithm.

The intended audience is narrower than "robotics in general". The README says Pinocchio was originally designed for robotics but can be used in biomechanics, computer graphics and vision. In practice the projects named as dependents point at a specific niche: Aligator, Crocoddyl, the Stack-of-Tasks controller framework and the Humanoid Path Planner all sit in the optimal-control and planning layer. If your work is trajectory optimization, system identification or gradient-based control, the derivative support is the reason to be here. If you want a renderer with a physics tab, this is the wrong layer.

How the algorithm layer is put together

The core is a C++ template library built on Eigen for linear algebra and coal for collision detection. The README describes it as header only, cache friendly, and able to support a custom scalar type. That last point is the architectural hinge: because the algorithms are templated on the scalar, the same code path can be instantiated over double, over a multiple-precision MPFR type, or over an automatic differentiation type from CppAD or CasADi. Derivatives are not bolted on through finite differences; the README states Pinocchio provides analytical derivatives of the main rigid body algorithms.

Model input goes through parsers for URDF, SDF, MJCF and SRDF, or the model can be built programmatically. Beyond open chains, the library handles closed-loop kinematic mechanisms, frictional contact problems and sparse constrained dynamics. The repository layout reflects the split: include/ for headers, src/ for sources, bindings/ for the Python layer, unittest/ and benchmark/ alongside. A Python interface is generated from the C++ core, so the Python API is a binding over the same algorithms rather than a separate implementation.

Installing Pinocchio and running a first computation

The README gives one line for conda, assuming Conda is already present. This pulls the package from conda-forge and brings the C++ library and the Python bindings together, which is the path the project points at for direct access to the Python interface.

Installing Pinocchio and running a first computation, continued

There is also a pip route, distributed under the name pin. The README states this is currently only available on Linux, so a macOS or Windows user should treat conda as the supported option.

Loading a model and reading a derivative

Once installed, the smallest useful step is to load a model and confirm the joint structure. The examples directory contains scripts such as examples/forward-dynamics-derivatives.py and examples/build-reduced-model.py, which are the reference points for the API shape. The exact call sequence is not reproduced in the README, so read those files before writing your own; the repository also ships models/ and points at example robot descriptions. The thing to check first is whether your description format is among URDF, SDF, MJCF and SRDF, because a model that fails to parse stops everything downstream.

Where Pinocchio is the wrong tool

The README does not document rollback or downgrade procedures, and it does not describe a stable ABI across major versions. The release history shows v3.9.0, then v4.0.0, then v4.1.0 within roughly nine months, so a project pinned to an older major should expect to re-verify its calls rather than assume drop-in behaviour. That is a real cost for anyone embedding the library in a long-lived product.

Two other boundaries are worth stating plainly. First, the pip package is Linux only per the README, so cross-platform Python deployment without conda is not covered. Second, Pinocchio is a dynamics and derivatives library, not a simulator with a scene graph and rendering: the README lists visualization as a separate concern, and collision detection is delegated to coal. If your requirement is a physics engine that draws the result, you are assembling that yourself. The README also describes the library as multi-thread friendly rather than promising a particular threading model, so concurrency behaviour needs its own validation.

Pinocchio against a finite-difference or general autodiff stack

The obvious alternative is to take a dynamics implementation and wrap it in a general automatic differentiation framework, or to approximate derivatives by finite differences. The difference is where the derivative comes from. Finite differences re-evaluate the dynamics at perturbed inputs, so cost scales with the number of inputs and accuracy depends on the step size. A general autodiff tool differentiates through whatever code you wrote, which works but produces a graph over the whole computation.

Pinocchio instead supplies analytical derivatives of the algorithms themselves, and it also interoperates with CppAD and CasADi rather than competing with them. That combination is the distinguishing choice: you can use the analytical derivatives directly, or instantiate the templated algorithms over an autodiff scalar when you need derivatives of something composed on top. The trade-off is that you inherit the library's model representation and its version cadence. A team already committed to a different dynamics backend will find the migration cost is in the model plumbing, not in the math.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-23. Releases are frequent: v3.9.0 on 2026-01-05, v4.0.0 on 2026-04-13, v4.1.0 on 2026-07-07. That cadence is good for bug fixes and bad for anyone who wants a frozen surface. The default branch is devel, which tells you where development lands first; the CHANGELOG.md file at the repository root is the place to read before upgrading, and the presence of .git-blame-ignore-revs suggests formatting churn is batched separately from logic changes.

The licence is BSD-2-Clause, a permissive licence that generally allows use in closed products provided the copyright notice and licence text are retained. That is a description of the licence identifier, not legal advice; have your own counsel review redistribution terms, particularly if you ship a modified copy. Because the library is header only and templated, a good part of the code is compiled into your binary, which matters for attribution and for build times. The repository also ships pixi.toml, pixi.lock, flake.nix and flake.lock, so reproducible development environments are provided for contributors, but those files are about building Pinocchio, not about pinning it as a dependency in your own project.

Editorial conclusion

Adopt Pinocchio if you need analytical derivatives of rigid body algorithms, closed-loop mechanism support, or a C++ core you can drive from Python, and if you can pin a conda-forge or ROS environment. Do not adopt it if you want a visual physics engine with built-in rendering, or if you need a pip wheel on Windows or macOS, since pip is documented as Linux only. Before committing, verify that your URDF, SDF or MJCF model loads through the parser and that the derivative quantities you need (for example the forward dynamics derivatives shown in examples/forward-dynamics-derivatives.py) are exposed for your chosen scalar type.

Frequently asked questions

Official sources

1. License: BSD-2-Clause
2. Project website
3. README
4. Releases
5. stack-of-tasks/pinocchio on GitHub