mink inverse kinematics for MuJoCo robot models

Why mink fits a MuJoCo robotics stack

mink addresses differential inverse kinematics, the repeated problem of finding a joint configuration that moves a robot toward a desired pose while respecting the model's constraints. Its intended users are Python developers and robotics researchers who already model robots or environments in MuJoCo. The repository includes examples for single and dual arms, arm and hand systems, dexterous hands, humanoids, legged robots, and mobile manipulators. That range indicates intended coverage, but it does not prove that every listed robot can be deployed without adapting its model or control configuration.

The library is not presented as a general motion planner. Its feature list centers on task specification, joint limits, collision constraints, and kinematic closure. This makes it more specific than a geometry utility that merely calculates end-effector poses. It also creates a clear integration boundary: users bring a MuJoCo model and formulate the desired motion as tasks for mink, rather than asking mink to discover a complete trajectory from scratch.

MuJoCo remains a substantive part of the stack. The package metadata requires `mujoco >= 3.10.0`, and the project describes mink as being based on the MuJoCo physics engine. An existing application already centered on MuJoCo avoids adding a second primary physics and kinematics framework, but a user who only needs a small batch of pose calculations may find that dependency unnecessary.

Tasks and constraints inside mink's IK formulation

mink supports tasks in either configuration space or operational space. Configuration-space tasks can work with joint quantities directly, while operational-space tasks concern a desired transform for a robot body. This distinction matters when a target is specified as an end-effector pose rather than as joint angles. The operational-space interface also requires the application to represent pose targets consistently with mink's Lie group interface.

Constraints are a first-class part of the feature set. mink documents limits on joint positions and joint velocities, as well as collision avoidance between any geom pair. Collision avoidance therefore operates through the MuJoCo model's geometry, not through a separate collision mesh supplied by the user. Geom selection and distance definitions still need to match the model, and the README does not explain automatic geom filtering or guarantee useful collision behavior for an incomplete model.

Closed chains are handled through MuJoCo equality constraints. This is useful for mechanisms whose forward kinematics cannot be represented accurately as an open tree. It also means that loop-closure behavior depends on the constraint setup in the MuJoCo model rather than being entirely an IK task-definition choice.

The package depends on `qpsolvers[daqp] >= 4.12.0`, which connects the constrained kinematics work to a numerical optimization solver. The README does not document solver selection, convergence diagnostics, failure returns, or performance limits. Engineers should therefore treat DAQP availability, solver status, and task feasibility as integration details to inspect in the API documentation rather than assume that every difficult target will converge.

Lie groups and native C acceleration

Rigid-body transformations are exposed through a Lie group interface. The repository says that matrix Lie group operations include native C optimization for inverse-kinematics hot paths. The source layout also contains `CMakeLists.txt`, while `pyproject.toml` uses `scikit-build-core>=0.10` as its build backend. Together, these files indicate that mink is not exclusively a pure-Python implementation.

This architecture is relevant when pose errors are repeatedly converted between coordinate representations during each IK step. A conventional implementation often has to translate rotation errors, transform updates, and body-level targets. Lie group operations provide a structure for those calculations, while the native component is intended to reduce Python overhead in common paths. The README does not publish a performance comparison, so the exact benefit cannot be inferred from the presence of optimization alone.

The transform code is adapted from `jaxlie`, and its mathematical implementation cites Joan Solà, Jérémie Deray, and Dinesh Atthuchutham's paper `A micro lie theory for state estimation in robotics`. This provenance is useful for engineers evaluating the mathematics, but it does not replace API-level verification. Application code must still supply transforms with the correct frame, rotation convention, and ordering expected by mink and MuJoCo.

Closed loops and hand or humanoid examples also show that transform handling extends beyond a single six-degree-of-freedom arm target. Even so, the README does not document every task type, supported transform representation, or numerical edge case.

Installing mink and running its first UR5e example

The package metadata requires Python 3.10 or newer. For a project managed with `uv`, the README gives the following PyPI installation command. Add it from the directory containing the project's `pyproject.toml`.

uv add mink

This installs mink and resolves its declared runtime dependencies, including MuJoCo, `qpsolvers[daqp]`, and `typing_extensions`. If building or running the project from a local clone is required, the documented sequence is:

git clone https://github.com/kevinzakka/mink.git && cd mink
uv sync

The repository's first listed robot example is the UR5e arm. On Linux, the README runs it with:

uv run examples/arm_ur5e.py

On macOS, the documented path first applies a repository script so that `mjpython` works with `uv`, then launches the same example through that interpreter:

./fix_mjpython_macos.sh  # So that mjpython works with uv.
uv run mjpython examples/arm_ur5e.py

The operating system distinction is a real setup constraint. Linux uses the normal Python execution path, while macOS requires `mjpython`. The README does not provide Windows installation or launch instructions, so it would be incorrect to assume the documented commands cover that platform.

For local development, the Makefile also defines a broader synchronization target. It installs all extras, packages, and the development dependency group:

uv sync --all-extras --all-packages --group dev

The project classifies version 1.3.0 as `Development Status :: 5 - Production/Stable`, declares itself compatible with Python 3.10 through 3.14, and lists the Apache-2.0 license.

Model coverage and operational failure points

The examples directory indicates broad robot-model coverage, including Franka Panda, UR5e, KUKA iiwa14, ALOHA 2, dual-arm systems, Allegro and LEAP hands, Shadow Hand, Unitree humanoids and quadrupeds, Spot, Cassie, TidyBot, and Stretch. This is a reason to inspect the repository if the target robot is already represented by an included example. It is not evidence that any hardware model can be copied without checking units, actuator definitions, joint ordering, and collision geometry.

Failure is likely to occur before the solver if a MuJoCo XML cannot load, a named site or body does not exist, or expected geoms are missing or incorrectly placed. The package does not remove that dependency. mink can constrain joint positions and velocities, but the documentation does not claim that these limits establish safe real-world actuation. Control frequency, motor response, payload limits, and controller safety are outside the stated feature set.

An IK solver can also reach a configuration that satisfies the formal task and constraints without matching the user's intended redundancy resolution. The README does not document null-space configuration, task priorities, weighting APIs, or behavior when targets are unreachable. Those omissions make the examples and full documentation necessary parts of adoption review.

Native C acceleration is most relevant when IK is called in a repeated control loop. It should not be interpreted as evidence that the complete MuJoCo simulation, collision detection, or visualization loop meets a particular latency target. The repository contains a `benchmarks/` directory, but the README does not describe its methodology or publish results.

mink versus Pink and Pinocchio-based IK

The clearest alternative named by the project is Pink. The README identifies mink as a direct port of Pink, which uses Pinocchio underneath. The architectural difference is therefore not merely packaging. Pink-centered systems place the IK layer on a Pinocchio-based stack, while mink uses MuJoCo as its physics and modeling foundation.

For a team already maintaining MuJoCo XML models, simulation contacts, visualizers, or control loops, staying with mink can reduce conceptual duplication across the stack. A team whose existing robot descriptions, kinematics utilities, and deployment dependencies are already built around Pinocchio and Pink may have less migration work by retaining that path. Neither option should be selected solely from the phrase "direct port": task coverage, constraint semantics, and model conversion costs still need direct comparison against the relevant API documentation.

Another possible alternative would be solving poses with a minimal kinematics package, but the README does not identify a specific package or establish behavioral parity. It would therefore be speculation to claim that a named lighter library supports equivalent collision, velocity, operational-space, and closed-chain features.

The practical comparison is integration fit. Mink is the documented choice when MuJoCo is already central. Pink is the documented existing alternative when the Pinocchio approach is already established.

Release activity, upgrades, and Apache-2.0 effects

The repository is not archived, and its last push was on 2026-09-30. Recent releases include `v1.3.0` on 2026-08-18, `v1.2.0` on 2026-06-20, and `v1.1.1` on 2026-05-15. The package metadata currently declares version `1.3.0`. This is a recent release record, although release frequency alone does not establish API stability for a particular integration.

The dependency floor of `mujoco >= 3.10.0` is important during upgrades because a mink upgrade can coincide with changes in the underlying model and simulation stack. The project includes `CHANGELOG.md`, which is the documented place to inspect release-specific changes, while `uv.lock` records the development environment's resolved packages. The README does not summarize compatibility decisions between individual mink and MuJoCo versions.

Native code also affects packaging. `pyproject.toml` requires `scikit-build-core>=0.10` and `numpy` in the build requirements. Downstream Python environments therefore need a build path that can satisfy those requirements. The README documents only `uv` workflows, so integrations using `pip`, conda, or constrained build environments need separate validation.

Mink is distributed under Apache-2.0, with the license declared in `pyproject.toml` and stored in `LICENSE`. That identifier is the relevant project-specific licensing fact. Review the actual `LICENSE` and `NOTICE` obligations for a particular distribution rather than treating this review as legal advice.

Editorial conclusion

Adopt mink when the robot model, contact representation, or simulation loop already uses MuJoCo and the required IK features match its task and constraint model. Do not choose it solely for basic offline IK when an independent kinematics stack would be easier to deploy. Verify first that the intended MuJoCo model loads correctly, that `qpsolvers[daqp] >= 4.12.0` resolves on the target system, and that the relevant example reproduces the intended task without requiring an unstated actuator or rendering setup.

Frequently asked questions

Official sources

1. kevinzakka/mink on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases