orocos_kinematics_dynamics: rigid body kinematics for real-time robot code

The problem: kinematics code that has to run in a control loop

Every robot needs to answer two questions continuously. Where is the end effector, given the joint angles. And what joint angles put the end effector where I want it. The first is forward kinematics, the second is inverse kinematics, and both have to be answered every cycle of a control loop rather than once at startup.

That runtime constraint shapes the whole design of a kinematics library, and it is the constraint the Orocos project names first. The project describes itself as an effort to supply RealTime usable kinematics and dynamics code, which is a specific claim: code structured so that it can be called from a periodic task, with the computations and the data representations built around that assumption rather than around a batch analysis.

The audience is robotics developers, and specifically the people who write the part of a robot stack between the planner and the actuators. That is a small, opinionated audience, which is why the library is a focused library rather than a framework. It does not schedule anything, it does not own your loop, and it does not try to be a robotics platform. It provides the mathematics and the representations, and leaves the architecture to you.

The repository carries a CI badge, a CHANGELOG.md and a .gitmodules file, and it is not archived with the last push on 2026-09-23. The published releases are 1.5.4 on 2026-09-01, 1.5.3 on 2025-10-17 and 1.5.2 on 2025-10-03, so the 1.5 series is the one being released.

What the library actually contains: kinematic structures and solvers

The project description names three things, and they are the three things a kinematics library needs to be useful.

The first is rigid body kinematics calculations. A rigid body here means a link, with a frame, a pose relative to its parent, and the joint that connects it to that parent, with its own type and axis. The library's job is to represent a chain or a tree of those and to answer questions about where the frames end up.

The second is representations for kinematic structures. This is the part that separates a serious library from a pile of functions. A serial chain and a branched tree are different data structures with different invariants, and the representation is what lets the solver code be written once. It is also what lets a caller inspect the structure, ask what its size is, and know that the answers are consistent.

The third is the solvers, for both inverse and forward kinematics. The inverse problem, finding joint angles that reach a target pose, is the hard one: it may have several solutions, or none, and the library's job is to return the answer together with the information about which case applies rather than a bare vector of numbers.

A library that provides all three is reusable across a whole robot stack, and the runtime usability claim only makes sense once the data representations are part of the package. A solver function that takes and returns plain arrays would be quick to write and awkward to use in a loop, because the caller would rebuild the structure on every call.

The project also describes the scope as including dynamics code, though the stated content of this repository is the kinematics calculations, the kinematic representations and the solvers. If you need a full dynamics engine, this is not the whole of it.

Two packages that must be version matched

The repository holds two things, and the relationship between them is the first thing a user needs to understand.

The C++ library lives in the orocos_kdl folder, and its installation instructions are in the INSTALL.md file inside that folder. The Python bindings live in the python_orocos_kdl folder, with their own INSTALL.md. The documentation is emphatic about how these two relate: always use the same version of the C++ library and the Python bindings, because a mismatch between them can cause many issues.

That is a specific and practical warning rather than a general disclaimer. The Python bindings wrap the C++ library, so a bindings package compiled against one version of the C++ headers and linked against another can fail in ways that are hard to trace, and the symptom will look like a runtime error in your script rather than a version mismatch. Keeping the pair in step is the fix, and the fact that the bindings are in the same repository, with the same tag, is the mechanism that makes it easy.

For a Python-heavy robotics stack, the practical workflow is to build the C++ library first, then the bindings against that same build, rather than installing one from a package manager and building the other from source.

The repository also carries a .gitmodules file, which means at least one component is pulled in as a submodule rather than vendored directly, so a source checkout needs its submodules initialised before the build will have everything it expects.

Building it: cmake and make are enough, and colcon is preferred under ROS 2

The build story is the part of this repository that has been thought about most, and the reason is that the library has to serve two quite different consumers.

Both packages declare a build type of cmake, so they also build with plain cmake and make without ROS, ament or colcon installed. That is a deliberate choice, and it matters: a kinematics library is useful outside robotics middleware. If you are writing a tool, a test harness or an offline analysis program that needs to solve a chain, you should not have to install a ROS distribution to get it.

Under ROS 2 the recommendation is different. The documentation states that when using ROS 2, it is preferred to use the colcon installation method over the cmake and make method. Colcon is the build tool of the ROS 2 ecosystem and it handles the workspace layout, the package discovery and the ament resource registration that a ROS 2 package needs to be found by the rest of the stack.

So there are two supported routes, and the choice is not a preference for one tool over another. Plain cmake and make when you want the library on its own. Colcon when you want it inside a ROS 2 workspace, where the package has to be discovered and built alongside everything else.

The detailed instructions are not in the repository README but in the two INSTALL.md files, one per package, which is where a first-time user should start.

The branch policy: master is ROS 2, the 1.5 line is the last with ROS 1

This repository has a maintenance policy that is unusual to find stated so plainly, and it changes how you should approach a checkout.

The master branch targets ROS 2 and builds with colcon and ament. The release-1.5 branch is the last one supporting ROS 1 and catkin, and the documentation states there will be no ROS Noetic release.

So the two supported worlds are on two different branches. If you are on ROS 1, you are on the 1.5 line, and there is no forward release for Noetic. If you are on ROS 2, master is where the work happens, and the 1.5.4 tag from 2026-09-01 is the most recent published release of the older line.

The consequence for an adopter is a decision that has to be made explicitly rather than by defaulting to the default branch. A team on Noetic should not expect the master branch to build for them, and a team on ROS 2 should not treat the 1.5 releases as current, because those releases are cut from the other branch.

The CI badge is for the master branch, which means the continuous integration signal you see covers the ROS 2 side of the project. The 1.5 line is maintained, and 1.5.4 was published in September 2026, but its changes are not what the CI badge is reporting on.

For a project that people depend on for the maths of a moving machine, that separation is the right way to do it. It also means the upgrade path from ROS 1 to ROS 2 for this library is a branch change rather than a version bump, and that is worth knowing before you build a plan around it.

The licence question, and what to check before you build on it

There is one thing about this repository that a careful reader should resolve before writing any code against it, and the documentation does not resolve it for you.

The licence field for the repository is recorded as unknown. The project description does not state a licence either. For a library that other people's robots depend on, that is a genuine gap rather than a formality, and it is the kind of thing that is easiest to fix and easiest to overlook.

What a prospective user can do is look inside the repository itself for the licence text and for the headers in the source files, and if the answer is still unclear, ask the project. Until that is answered, the safe assumption for a commercial or redistributed product is that you do not have permission to do anything beyond evaluating the code, and that assumption should be resolved before, not after, you build on it.

There is also a second thing to verify, which the repository structure hints at but does not spell out. The .gitmodules file means part of the tree comes from elsewhere, and code pulled in as a submodule carries the licence of its own project rather than of this one. If a submodule is a substantial part of the library, its terms matter as much as the top-level ones.

Beyond the licence, the practical checks are short. Decide your branch first, ROS 1 or ROS 2, because that determines everything else. Build the C++ library and the Python bindings from the same tag, because the documentation warns that a version mismatch between them causes problems. Read the two INSTALL.md files rather than the project description for the build steps. And check the CHANGELOG.md between the release you would pin and the current tip, because with releases in the 1.5 series and a moving master branch, the difference between them is where the behavioural changes live.

Editorial conclusion

Adopt orocos_kinematics_dynamics if you are writing robot control code that has to run inside a control loop and you want forward and inverse kinematics with a Python interface alongside it. Do not adopt it if you need dynamics with forces and torques solved in full, since the project describes itself as supplying kinematics and dynamics code with the kinematics and solver representations as its stated content. Before you build, check which branch matches your middleware, because master targets ROS 2 with colcon and ament while the 1.5 line is the last with ROS 1 support, and check the licence yourself, because the repository records none.

Frequently asked questions

Official sources

1. Issues
2. orocos/orocos_kinematics_dynamics on GitHub
3. README
4. Releases