{"id":5366,"library":"pin","title":"Pinocchio","description":"Pinocchio is a library for efficiently computing the dynamics (and derivatives) of a robot model, or of any articulated rigid-body model. It is primarily written in C++ with comprehensive Python bindings, leveraging Eigen for linear algebra and FCL for collision detection. It provides state-of-the-art rigid body algorithms and their analytical derivatives. The current version is 3.9.0, with frequent minor and patch releases.","status":"active","version":"3.9.0","language":"en","source_language":"en","source_url":"https://github.com/stack-of-tasks/pinocchio","tags":["robotics","dynamics","kinematics","rigid-body","control","simulation","optimization"],"install":[{"cmd":"pip install pin","lang":"bash","label":"PyPI (Linux only, as per some docs)"},{"cmd":"conda install pinocchio -c conda-forge","lang":"bash","label":"Conda (Recommended for full dependency management)"}],"dependencies":[{"reason":"Python bindings for Eigen objects are exposed as NumPy arrays.","package":"numpy","optional":false},{"reason":"Provides common robot models (e.g., UR5) used in examples and for quick testing.","package":"example-robot-data","optional":true},{"reason":"A common Python-based 3D viewer for visualization.","package":"meshcat","optional":true},{"reason":"A C++ viewer with Python bindings for visualization.","package":"gepetto-viewer","optional":true},{"reason":"A Python-based viewer for visualization.","package":"panda3d_viewer","optional":true},{"reason":"Python bindings for Eigen; often a dependency or used internally.","package":"eigenpy","optional":false}],"imports":[{"note":"Commonly imported as 'pin' for brevity: `import pinocchio as pin`.","symbol":"pinocchio","correct":"import pinocchio"}],"quickstart":{"code":"import pinocchio as pin\nimport numpy as np\n\n# Create a simple 6-DOF kinematic chain (built-in sample model)\nmodel = pin.buildSampleModelManipulator()\ndata = model.createData()\n\n# Get model information\nprint(f\"Model name: {model.name}\")\nprint(f\"Number of joints: {model.nq}\")\n\n# Sample a random configuration\nq = pin.randomConfiguration(model)\nprint(f\"Random configuration (q): {q.T}\")\n\n# Perform forward kinematics\npin.forwardKinematics(model, data, q)\n\n# Update all the placements for the joints and frames\npin.updateFramePlacements(model, data)\n\n# Print the position of the end-effector frame\nEE_frame_idx = model.getFrameId(\"joint6\") # Assuming 'joint6' is the end-effector\nif EE_frame_idx < model.nframes:\n    print(f\"End-effector (joint6) position: {data.oMf[EE_frame_idx].translation.T}\")\nelse:\n    print(\"End-effector frame 'joint6' not found in model.\")\n\n# Example for loading a URDF (requires 'example-robot-data' and a URDF file)\n# from example_robot_data import loadUR\n# robot = loadUR(robot_name='ur5')\n# model_urdf = robot.model\n# data_urdf = model_urdf.createData()\n# q_urdf = pin.randomConfiguration(model_urdf)\n# print(f\"URDF model name: {model_urdf.name}, random config: {q_urdf.T}\")","lang":"python","description":"This quickstart demonstrates how to create a simple robot model using a built-in sample, generate a random configuration, and perform forward kinematics to find the end-effector position. It also includes commented lines for loading a URDF model, which typically requires the `example-robot-data` package."},"warnings":[{"fix":"Consult the 'Porting from Pinocchio 2 to 3' section in the official documentation for detailed migration steps. Review changed function names, removed methods, and updated module structures.","message":"Migrating from Pinocchio 2.x to 3.x involves significant API changes. Many deprecated functions from version 2.x have been removed, and several functions/headers have been renamed or moved. The library's internal structure was also split into multiple CMake targets.","severity":"breaking","affected_versions":"2.x to 3.x"},{"fix":"Ensure your Python environment (especially Conda) is correctly configured, and all dependencies (like `boost-python`) are built for your specific Python version. Using `conda install pinocchio -c conda-forge` is often more robust than `pip install pin` for managing these complex dependencies. If building from source, ensure correct Boost.Python linking.","message":"Python version compatibility can be sensitive, particularly with Python 3.10 and newer versions or specific environments (e.g., Conda, Arch Linux). Users may encounter `ImportError` or unexpected crashes if `pinocchio` binaries are linked against an incompatible `Boost.Python` version (e.g., built for Python 3.8 trying to run on 3.10). Pinocchio 3.9.0 explicitly states Python 3.10 as the minimal supported version.","severity":"gotcha","affected_versions":"3.x"},{"fix":"Install your preferred viewer using `pip install <viewer_package>` (e.g., `pip install meshcat`) or `conda install -c conda-forge <viewer_package>` before attempting visualization examples. Refer to Pinocchio's documentation for specific viewer installation instructions and usage.","message":"Visualization tools (like Meshcat, Gepetto Viewer, Panda3D Viewer, RViz) are not part of the core `pin` (pinocchio) package and must be installed separately. The examples and tutorials often assume one of these viewers is available, leading to errors if they are not installed or configured.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to the latest Pinocchio version, which may handle these errors more gracefully with Python exceptions. When debugging, ensure input configurations (`q`), velocities (`vq`), and accelerations (`aq`) match the model's `nq` and `nv` dimensions respectively. If compiling from source, ensure `NDEBUG` is defined for release builds to disable assertions, or use `model.check(data)` explicitly to perform checks.","message":"In older Pinocchio versions, C++ assertion failures (e.g., due to incorrect input vector sizes for model or data) could lead to a hard crash of the Python interpreter, rather than raising a Python exception. This behavior was tied to how the C++ library was compiled (assertions enabled, `NDEBUG` undefined).","severity":"gotcha","affected_versions":"Potentially older 2.x and early 3.x releases (especially pre-compiled apt packages)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}