Repository files navigation

Import open source robot descriptions as Python modules.

Importing a description for the first time automatically downloads and caches files for future imports. MostAwesome Robot Descriptions are available. All of them load successfully in respectively MuJoCo (MJCF) or Pinocchio, iDynTree, PyBullet and yourdfpy (URDF).

conda install -c conda-forge robot_descriptions

pip install robot_descriptions

The library providesload_robot_description functions that return an instance of a robot description directly usable in the corresponding software. For example:

fromrobot_descriptions.loaders.pinocchioimportload_robot_descriptionrobot=load_robot_description("upkie_description")

Loaders are implemented for the following robotics software:

Loading will automatically download the robot description if needed, and cache it to a local directory.

You can useuv to manipulate robot descriptions directly from the command line:

uvx robot_descriptions pull iiwa14_description          # download the robot description to cacheuvx robot_descriptions show_in_meshcat go2_description  # display the robot description

Tryuvx robot_descriptions -h to see the list of available commands. Alternatively, once the package is installed from PyPI or conda-forge, you can call therobot_descriptions alias directly from the command line, or replaceuvx byuv run, orpython -m robot_descriptions (old school).

You can also import a robot description directly as a submodule ofrobot_descriptions:

fromrobot_descriptionsimportmy_robot_description

The import will automatically download the robot description if you don't have it already, and cache it to a local directory. The submodule then provides the following paths:

URDF_PATH /MJCF_PATH

Path to the main URDF/MJCF file of the robot description.

PACKAGE_PATH

Path to the root of the robot description package.

REPOSITORY_PATH

Path to the working directory of the git repository hosting the robot description.

Some robot descriptions include additional fields. For instance, theiiwa14_description exportsURDF_PATH_POLYTOPE_COLLISION with more detailed collision meshes.

Loading a robot description:

• iDynTree
• MuJoCo
• Pinocchio
• PyBullet
• RoboMeshCat
• yourdfpy

Visualizing a robot description:

• MeshCat
• MuJoCo
• PyBullet
• RoboMeshCat
• yourdfpy

Available robot descriptions (gallery) are listed in the following categories:

• Arms
• Bipeds
• Dual arms
• Drones
• Educational
• End effectors
• Humanoids
• Mobile manipulators
• Quadrupeds
• Wheeled

The DOF column denotes the number of actuated degrees of freedom.

New robot descriptions are welcome! Check out theguidelines then open a PR.

Thanks to the maintainers of all the git repositories that made these robot descriptions available.

If you use this project in your works, please cite as follows:

@software{robot_descriptions_py,title ={{robot_descriptions.py: Robot descriptions in Python}},author ={Caron, Stéphane and Romualdi, Giulio and Kozlov, Lev and Ordoñez Apraez, Daniel Felipe and Tadashi Kussaba, Hugo and Bang, Seung Hyeon and Zakka, Kevin and Schramm, Fabian and Uru\c{c}, Jafar and Traversaro, Silvio and Zamora, Jonathan and Castro, Sebastian and Tao, Haixuan Xavier and Yu, Justin and Jallet, Wilson and Zhang, Yutong},license ={Apache-2.0},url ={https://github.com/robot-descriptions/robot_descriptions.py},version ={1.22.0},year ={2025}}

Don't forget to add yourself to the BibTeX above and toCITATION.cff if you contribute to this repository.

• Awesome Robot Descriptions: curated list of robot descriptions in URDF, Xacro or MJCF formats.
• drake_models: collection of URDF and SDF descriptions curated for the Drake framework.
• MuJoCo Menagerie: collection of MJCF robot descriptions curated for the MuJoCo physics engine.
• robot_descriptions.cpp: package to userobot_descriptions.py in C++.