robot-descriptions/robot_descriptions.py

robot‑descriptions – Python library for robot model assets

What it is – A pure‑Python package that lets you import open‑source robot description files (URDF, MJCF, etc.) as regular Python modules. The first time you request a robot, the library automatically downloads the description from the curated Awesome Robot Descriptions collection, caches it locally, and then hands you a ready‑to‑use object for a variety of simulation and analysis tools.

Why it matters – Robotics research and development often require the same set of robot models (e.g., KUKA iiwa, Franka Panda, Boston Dynamics Spot). Keeping those files in sync across projects is a pain. robot_descriptions solves that by providing a single source‑of‑truth, version‑controlled on GitHub, and reachable via a tiny Python API. It works with the most common robot‑software stacks, so you can switch between MuJoCo, Pinocchio, PyBullet, iDynTree, RoboMeshCat, or yourdfpy without manually handling files.

Installation

# conda‑forge (recommended for scientific Python stacks)
conda install -c conda-forge robot_descriptions

# or via pip
pip install robot_descriptions

Basic usage (Python)

from robot_descriptions.loaders.pinocchio import load_robot_description

# Returns a Pinocchio model ready for kinematics / dynamics calls
robot = load_robot_description("upkie_description")

The library ships a loader for each supported backend:

Backend	Loader module
iDynTree	`robot_descriptions.loaders.idyntree`
MuJoCo	`robot_descriptions.loaders.mujoco`
Pinocchio	`robot_descriptions.loaders.pinocchio`
PyBullet	`robot_descriptions.loaders.pybullet`
RoboMeshCat	`robot_descriptions.loaders.robomeshcat`
yourdfpy	`robot_descriptions.loaders.yourdfpy`

Each loader downloads the requested description (if not cached) and returns an object native to that framework.

Command‑line interface

The package also ships a tiny CLI (exposed via the robot_descriptions entry‑point or uvx robot_descriptions). Example commands:

# Pre‑download a model
uvx robot_descriptions pull iiwa14_description

# Visualise in MuJoCo (requires the optional mujoco‑python‑viewer)
uvx --with mujoco-python-viewer robot_descriptions show_in_mujoco go2_mj_description

# Visualise in MeshCat
uvx --with meshcat robot_descriptions show_in_meshcat go2_description

The CLI mirrors the Python API: pull caches, show_in_* launches a viewer for the chosen backend.

Importing a description as a submodule

You can treat a robot description like a regular Python submodule:

from robot_descriptions import panda_description

print(panda_description.URDF_PATH)          # path to the main URDF file
print(panda_description.PACKAGE_PATH)       # root of the description package
print(panda_description.REPOSITORY_PATH)    # the cloned git repo location

Some packages expose extra constants (e.g., URDF_PATH_POLYTOPE_COLLISION for high‑detail collision meshes) or Xacro handling (XACRO_PATH + optional XACRO_ARGS).

What robot models are available?

The library indexes the Awesome Robot Descriptions gallery. Models are grouped by type (arms, bipeds, quadrupeds, drones, etc.) and include both URDF and MJCF variants where available. A few examples:

panda_description / panda_mj_description (Franka Emika Panda)
iiwa14_description / iiwa14_mj_description (KUKA iiwa‑14)
go2_description (Unitree Go2 quadruped)
omx_f_description (ROBOTIS OpenManipulator‑F)
low_cost_robot_arm_mj_description (a simple MJCF arm from DeepMind’s menagerie)

Each entry lists the original maintainer, file format, and license (BSD‑3, Apache‑2.0, MIT, GPL‑3, etc.).

Example scripts (in the repo)

The repository ships ready‑to‑run examples showing how to load a model in each supported backend and how to visualise it:

examples/load_in_pinocchio.py
examples/show_in_meshcat.py
examples/show_in_mujoco.py …and equivalents for iDynTree, PyBullet, RoboMeshCat, and yourdfpy.

Who might use this?

Researchers building simulation pipelines that need many robot models.
Robotics educators who want students to experiment with a variety of arms and mobile platforms without hunting down files.
Developers of simulation‑to‑real pipelines who need a reliable way to fetch the exact URDF/MJCF used during training.

License & contribution

The library itself is released under the MIT license (see the PyPI badge). Robot description files retain their original upstream licenses, which are displayed in the generated tables. Contributions are welcome – see the CONTRIBUTING.md badge for details.

Bottom line – robot_descriptions is a lightweight, well‑tested bridge between the world of open‑source robot model repositories and the Python‑centric robotics ecosystem, handling download, caching, and format conversion automatically.