urdf2any

Convert URDF robot descriptions to USD (OpenUSD / Isaac Sim) and MJCF (MuJoCo) — in pure Python, with no Isaac Sim, Omniverse, or GPU required.

• Self-contained — runs anywhere pip works (usd-core, trimesh, numpy)
• One source of truth — a single simulator-agnostic intermediate representation drives both backends, so USD and MJCF describe the same physical robot
• Verified — output is checked in CI against the real reference implementations: the IsaacLab URDF importer (golden comparison) and MuJoCo's native URDF loader (live comparison)

Installation

pip install urdf2any

The base install covers URDF → USD / MJCF conversion. Optional extras unlock features that need an extra dependency:

Extras combine: pip install "urdf2any[mjcf-validate,skin]".

Quick start

The output format is inferred from the file extension:

urdf2any robot.urdf -o robot.usd   # USD (UsdPhysics articulation)
urdf2any robot.urdf -o robot.xml   # MJCF (with actuators)

Or from Python:

from urdf2any import convert, ConvertConfig, JointDriveCfg

convert(
    "robot.urdf",
    "robot.usd",
    ConvertConfig(joint_drive=JointDriveCfg(stiffness=100.0, damping=1.0)),
)

By default every URDF link becomes one body and no lossy transformation is applied — the same config yields the same robot in both formats.

MuJoCo skins

Install urdf2any[skin], then attach a triangulated skinned DAE to MJCF:

urdf2any robot.urdf -o robot.xml --skin shell.dae \
  --skin-bone BoneA=base --skin-bone BoneB=upper_link

Map every weighted bone's Collada joint sid to a URDF link. Bone rest positions must match the robot's zero pose; with fixed-joint merging, map to surviving link frames. Skin files, textures, and MJCF asset entries are generated automatically. Distinct textures need unique file names; after renaming, update the DAE references. Skins are visual only; keep collision geometry in the URDF.

Compatibility presets

To reproduce the behavior of an existing converter, start from a preset; individual flags still override it:

urdf2any robot.urdf -o robot.usd --preset isaaclab   # IsaacLab URDF importer defaults
urdf2any robot.urdf -o robot.xml --preset mujoco     # MuJoCo native URDF conversion

The same presets are available in Python as ConvertConfig.isaaclab() / ConvertConfig.mujoco(), and their definitions are what the parity test suites validate against the real implementations.

Options

Conversion flags correspond to ConvertConfig fields, mostly under the same name in snake_case. The exceptions:

• --keep-fixed-link-inertials sets merge_fixed_ignore_inertia=False
• --exclude-geometry patterns go in the exclude_geometry_names list
• --no-actuators sets mjcf_add_actuators=False
• the --joint-* flags fill the nested drive config: ConvertConfig(joint_drive=JointDriveCfg(target_type=..., stiffness=..., damping=...))
• --skin, --skin-bone, and the General table below are CLI-only; in Python, mesh_root is an argument of convert / parse_urdf, not a config field

General

Physics & structure

Joint drives

MJCF only

Feature support

Robot-specific preprocessing (renaming links, removing parts) is deliberately out of scope: parse with parse_urdf, mutate the IR, then emit with convert_robot.

Development

uv sync
uv run pytest        # includes the parity suites (CPU only)
uv run ruff check .

Releases are published to PyPI by pushing a vX.Y.Z tag (Trusted Publishing via .github/workflows/release.yml).

Parity testing

• USD vs IsaacLab importer — tests/test_golden_parity.py diffs urdf2any's output against committed golden summaries (tests/golden/) generated by the real importer. Regenerate them inside an IsaacLab container with scripts/generate_reference.py (the import itself needs no GPU).
• MJCF vs MuJoCo — tests/test_mjcf_parity.py compiles both urdf2any's MJCF and the source URDF with MuJoCo and compares the resulting models live; no golden files needed.

Sample robots under tests/assets/ are vendored from IsaacLab (BSD-3-Clause) and Isaac Sim (Apache-2.0); see the NOTICE file next to each.

License

Apache-2.0