robot_descriptions.py

Robot descriptions in Python

(opens in a new tab) (opens in a new tab) (opens in a new tab) (opens in a new tab) (opens in a new tab) (opens in a new tab)

Import open source robot descriptions as Python modules.

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

Installation

From conda-forge

conda install -c conda-forge robot_descriptions

From PyPI

pip install robot_descriptions

Usage

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

from robot_descriptions.loaders.pinocchio import load_robot_description

robot = 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.

Command line

You can use uv (opens in a new tab) to manipulate robot descriptions directly from the command line:

# Download a robot description to cache
uvx robot_descriptions pull iiwa14_description

# Display a robot description
uvx --with mujoco-python-viewer robot_descriptions show_in_mujoco go2_mj_description
uvx --with meshcat --with pin robot_descriptions show_in_meshcat go2_description
uvx --with robomeshcat robot_descriptions show_in_meshcat go2_description
uvx --with pybullet robot_descriptions show_in_pybullet go2_description
uvx --with yourdfpy robot_descriptions show_in_yourdfpy go2_description

Try uvx robot_descriptions -h to see the list of available commands. Alternatively, once the package is installed from PyPI or conda-forge, you can call the robot_descriptions alias directly from the command line, or replace uvx by uv run, or python -m robot_descriptions (old school).

Import as submodule

You can also import a robot description directly as a submodule of robot_descriptions:

from robot_descriptions import my_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:

Some robot descriptions include additional fields. For instance, the iiwa14_description exports URDF_PATH_POLYTOPE_COLLISION with more detailed collision meshes.

Descriptions can also define XACRO_PATH (and optional XACRO_ARGS) instead of a static URDF_PATH. In that case, robot_descriptions renders the Xacro to a cached URDF transparently when loading the description.

Examples

Loading a robot description:

• iDynTree (opens in a new tab)
• MuJoCo (opens in a new tab)
• Pinocchio (opens in a new tab)
• PyBullet (opens in a new tab)
• RoboMeshCat (opens in a new tab)
• yourdfpy (opens in a new tab)

Visualizing a robot description:

• MeshCat (opens in a new tab)
• MuJoCo (opens in a new tab)
• PyBullet (opens in a new tab)
• RoboMeshCat (opens in a new tab)
• yourdfpy (opens in a new tab)

Descriptions

Available robot descriptions (gallery (opens in a new tab)) 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. Descriptions may appear in more than one category when tags overlap.

Arms

Bipeds

Dual arms

Drones

Educational

End effectors

Humanoids

Mobile manipulators

Quadrupeds

Wheeled

Contributing

New robot descriptions are welcome! Check out the guidelines (opens in a new tab) then open a PR.

Thanks

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

Citation

If you use this project in your work, 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 and Walker, Nick and Bragin, Nikita and Wie, Woojin and Skuric, Antun},
  license = {Apache-2.0},
  url = {https://github.com/robot-descriptions/robot_descriptions.py},
  version = {3.3.0},
  year = {2026}
}

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

See also

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