Written and maintained by CASRAI Editorial Board
Last updated
The Unified Robot Description Format (URDF) is an XML specification used across the Robot Operating System (ROS and ROS 2) ecosystem to represent the physical geometry, kinematic topology, and inertial dynamics of robotic systems. In computational robotics and embodied artificial intelligence, URDF provides the foundational mechanical description required for kinematic coordinate transformation, forward and inverse kinematics, 3D visualization, collision checking, and physics-based dynamic simulation. Adhering to scientific software engineering standards ensures that robot descriptions remain modular, validated, and reproducible across diverse laboratory simulations.
What It Is Used for in Research
In academic and industrial robotics research, URDF serves as the central data contract between hardware specifications, software algorithms, and simulation environments. Researchers use URDF across three primary domains:
- Kinematic State Estimation and Coordinate Frames: The
robot_state_publishernode parses a URDF model along with real-time joint positions to calculate forward kinematics. It broadcasts 3D transformation trees via thetf2library, allowing perception nodes to transform sensor readings (such as depth cameras and LiDAR) into base reference frames. - Motion Planning and Manipulation: Frameworks such as MoveIt 2 ingest URDF files to compute inverse kinematics, plan collision-free trajectories for robotic manipulators, and identify joint space singularities based on configured angular and velocity boundaries.
- Dynamic Simulation: Physics simulators (including Gazebo, Webots, and ODE) use the mass properties and inertia tensors defined in URDF to model gravitational loads, contact forces, and joint torques during controller evaluation. Releasing verified robot models under an open-source software license enables independent laboratories to validate and reproduce experimental findings.
Install or Access
URDF tools are standardized by Open Robotics and distributed via official Ubuntu/Debian software repositories. For standalone syntax validation, the underlying C++ parser and diagnostic binaries are provided in the liburdfdom-tools package without requiring a complete ROS desktop installation.
To install the standalone validation suite on Debian or Ubuntu:
sudo apt update
sudo apt install liburdfdom-toolsTo access the complete URDF modeling, xacro macro processing, and RViz2 visualization toolchain within a ROS 2 development environment (such as Rolling or Humble):
sudo apt install ros-${ROS_DISTRO}-urdf ros-${ROS_DISTRO}-xacro ros-${ROS_DISTRO}-robot-state-publisher ros-${ROS_DISTRO}-joint-state-publisher-gui ros-${ROS_DISTRO}-rviz2The official source repositories and parser C++ libraries (urdfdom and urdfdom_headers) are maintained on GitHub under the BSD 3-Clause license.
Step-by-Step Task
The following step-by-step procedure demonstrates how to author, assemble, and validate a syntactically correct URDF model for a two-link robotic arm with one rotational joint.
-
Define the Root Link: Every URDF model requires a base link that represents the root coordinate frame. The root link contains inertial, visual, and collision elements:
<link name="base_link"> <inertial> <origin xyz="0 0 0.1" rpy="0 0 0" /> <mass value="5.0" /> <inertia ixx="0.05" ixy="0.0" ixz="0.0" iyy="0.05" iyz="0.0" izz="0.05" /> </inertial> <visual> <origin xyz="0 0 0.1" rpy="0 0 0" /> <geometry> <cylinder radius="0.1" length="0.2" /> </geometry> <material name="slate"> <color rgba="0.2 0.2 0.3 1.0" /> </material> </visual> <collision> <origin xyz="0 0 0.1" rpy="0 0 0" /> <geometry> <cylinder radius="0.1" length="0.2" /> </geometry> </collision> </link> -
Define the Child Arm Link: Create the articulated forearm rigid body, specifying its physical dimensions and center of mass:
<link name="arm_link"> <inertial> <origin xyz="0 0 0.25" rpy="0 0 0" /> <mass value="2.0" /> <inertia ixx="0.04" ixy="0.0" ixz="0.0" iyy="0.04" iyz="0.0" izz="0.01" /> </inertial> <visual> <origin xyz="0 0 0.25" rpy="0 0 0" /> <geometry> <box size="0.08 0.08 0.5" /> </geometry> <material name="orange"> <color rgba="0.9 0.4 0.1 1.0" /> </material> </visual> <collision> <origin xyz="0 0 0.25" rpy="0 0 0" /> <geometry> <box size="0.08 0.08 0.5" /> </geometry> </collision> </link> -
Connect the Links with a Constrained Joint: Attach
arm_linktobase_linkusing arevolutejoint. Specify the rotation axis along the Z-axis and define physical angular and effort limits:<joint name="base_to_arm" type="revolute"> <parent link="base_link" /> <child link="arm_link" /> <origin xyz="0 0 0.2" rpy="0 0 0" /> <axis xyz="0 0 1" /> <limit lower="-1.5708" upper="1.5708" effort="30.0" velocity="1.5708" /> <dynamics damping="0.1" friction="0.05" /> </joint> -
Assemble the Complete Robot Description: Wrap all links and joints within the root
<robot>element and save the file asmanipulator.urdf:<?xml version="1.0"?> <robot name="two_link_manipulator"> <link name="base_link"> <inertial> <origin xyz="0 0 0.1" rpy="0 0 0" /> <mass value="5.0" /> <inertia ixx="0.05" ixy="0.0" ixz="0.0" iyy="0.05" iyz="0.0" izz="0.05" /> </inertial> <visual> <origin xyz="0 0 0.1" rpy="0 0 0" /> <geometry> <cylinder radius="0.1" length="0.2" /> </geometry> <material name="slate"> <color rgba="0.2 0.2 0.3 1.0" /> </material> </visual> <collision> <origin xyz="0 0 0.1" rpy="0 0 0" /> <geometry> <cylinder radius="0.1" length="0.2" /> </geometry> </collision> </link> <joint name="base_to_arm" type="revolute"> <parent link="base_link" /> <child link="arm_link" /> <origin xyz="0 0 0.2" rpy="0 0 0" /> <axis xyz="0 0 1" /> <limit lower="-1.5708" upper="1.5708" effort="30.0" velocity="1.5708" /> <dynamics damping="0.1" friction="0.05" /> </joint> <link name="arm_link"> <inertial> <origin xyz="0 0 0.25" rpy="0 0 0" /> <mass value="2.0" /> <inertia ixx="0.04" ixy="0.0" ixz="0.0" iyy="0.04" iyz="0.0" izz="0.01" /> </inertial> <visual> <origin xyz="0 0 0.25" rpy="0 0 0" /> <geometry> <box size="0.08 0.08 0.5" /> </geometry> <material name="orange"> <color rgba="0.9 0.4 0.1 1.0" /> </material> </visual> <collision> <origin xyz="0 0 0.25" rpy="0 0 0" /> <geometry> <box size="0.08 0.08 0.5" /> </geometry> </collision> </link> </robot> -
Validate Syntax with check_urdf: Run the terminal command to parse the XML file and verify tree integrity:
check_urdf manipulator.urdf -
Expand Macros When Working with Xacro Files: If your project uses modular Xacro macros, compile the file into standard URDF prior to parsing:
ros2 run xacro xacro manipulator.urdf.xacro -o manipulator.urdf
Output and How to Read It
When check_urdf successfully validates a model, it prints the robot name, confirms successful XML parsing, and displays the reconstructed kinematic hierarchy:
robot name is: two_link_manipulator
---------- Successfully Parsed XML ---------------
root Link: base_link has 1 child(s)
child(1): arm_linkTo inspect the parsed output:
- Root Link: Identifies the top-level rigid body that has no parent joint. If multiple root links appear, the URDF is disconnected and invalid.
- Child Tree: Each indented link confirms an established parent-child joint transformation. Verify that every articulated degree of freedom is correctly nested under its corresponding parent link.
- Graphical Graphviz Generation: Researchers can generate a visual schematic of the link and joint transformations using
urdf_to_graphiz:urdf_to_graphiz manipulator.urdfThis generates
two_link_manipulator.gvand compiles a PDF diagram (two_link_manipulator.pdf) showing exact frame offsets and joint axes.
Confirming syntax validity via check_urdf does not guarantee physical simulation stability. Physics engines require non-zero mass and positive-definite inertia tensors that satisfy physical triangle inequalities. Documenting these model parameters in data and model availability statements supports reproducible experimental verification.
Troubleshooting
The following table addresses common authoring errors encountered during URDF parsing and simulation:
| Symptom or Error | Root Cause | Resolution |
|---|---|---|
Root link has multiple parents or loop detected |
URDF strictly requires an acyclic directed tree. A child link has been assigned to more than one parent joint or forms a closed kinematic loop. | Ensure every child link appears in exactly one joint definition. For parallel mechanisms (such as four-bar linkages), migrate the simulation model to SDF or MJCF. |
Joint limit attribute missing |
A revolute or prismatic joint was declared without the mandatory <limit> tag specifying lower, upper, effort, and velocity. |
Add the <limit> element with all four required attributes. For unbounded continuous joints (like wheels), change the joint type to continuous. |
| Physics engine crashes or produces NaN velocities | The inertia tensor values (ixx, iyy, izz) are negative, zero, or violate physical triangle inequalities (where the sum of any two principal moments must be greater than or equal to the third). |
Calculate exact principal moments of inertia using standard 3D CAD export tools (such as SolidWorks URDF Exporter or MeshLab) or analytical solid formulas. |
Could not open resource: package://... |
A mesh file path referenced in <mesh filename="package://..." /> cannot be resolved because the ROS workspace is not sourced. |
Source the workspace overlay containing the mesh package, or use relative file paths (file://) when testing with standalone tools outside of ROS. |
| RViz2 displays untextured white shapes | Missing <material> elements inside the visual tag, or the robot_state_publisher node is not publishing coordinate transforms. |
Define RGBA color tags within <material> or specify texture paths, and verify that joint_state_publisher is running. |
Free Alternatives
While URDF is the default robot description format in ROS, specialized research applications often require capabilities beyond acyclic rigid trees. The following table compares free, open research alternatives for robot modeling:
| Format / Tool | Governing Organization & License | Kinematic Topology | Physics & Environmental Scope | Best Research Application |
|---|---|---|---|---|
| URDF | Open Robotics (BSD 3-Clause) | Strict tree (acyclic only) | Rigid-body kinematics, collision shapes, visual meshes | ROS / ROS 2 coordinate transformations, MoveIt 2 motion planning, RViz2 monitoring. |
| SDF (Simulation Description Format) | Open Robotics (Apache 2.0) | General kinematic graphs (supports closed loops) | Multi-robot systems, environmental terrain, lighting, physics sensors | High-fidelity Gazebo physics simulation, parallel linkage manipulators, field robotics. |
| MJCF (MuJoCo XML Format) | Google DeepMind (Apache 2.0) | Tree structures with equality constraints and tendons | High-performance contact dynamics, soft contacts, muscle actuators | Reinforcement learning, robotic locomotion, biomechanical motor control research. |
| USD / PhysX | Pixar & NVIDIA (Apache 2.0) | Layered hierarchical scene graph | Multi-material physics, GPU-accelerated parallel simulation, ray tracing | Embodied AI foundation models, NVIDIA Isaac Sim photorealistic synthetic data. |
| Proto (Webots Robot Specification) | Cyberbotics (Apache 2.0) | Hierarchical VRML97 procedural nodes | Integrated multi-body physics (ODE), sensors, autonomous vehicle tools | Cross-platform educational robotics, multi-robot swarm algorithm benchmarks. |
When publishing novel robot platforms or software packages alongside academic articles, authors can consult guidelines on software artifact publication to deposit executable model descriptions in public repositories.
FAQ
What is the difference between URDF and Xacro?
URDF is a pure XML specification that explicitly defines individual links and joints without support for programming constructs. Xacro (XML Macros) is an XML preprocessor that extends URDF by introducing reusable macros, variable assignments, mathematical expressions, and modular file includes. Because standard ROS parsers and check_urdf only accept pure XML, Xacro files (typically ending in .xacro or .urdf.xacro) must be processed through the xacro executable before being loaded into robot description parameters.
Can URDF model closed-loop kinematic mechanisms such as four-bar linkages?
No. URDF strictly enforces an acyclic tree topology where every link has at most one parent joint. Closed-loop mechanisms—such as parallel delta robots, Stewart platforms, or five-bar linkages—cannot be natively defined in URDF without introducing artificial kinematic cuts. Researchers modeling closed loops typically transition to SDF within Gazebo or MJCF in MuJoCo, both of which support closed kinematic chains and loop closure constraints natively.
What coordinate frames and physical units does URDF use?
URDF standardizes on International System of Units (SI) conventions: linear dimensions are expressed in meters, angular measurements in radians, mass in kilograms, joint effort in Newtons (prismatic) or Newton-meters (revolute), and velocity in meters per second or radians per second. All local coordinate systems follow the right-handed Cartesian frame convention, where the positive X-axis points forward, the positive Y-axis points to the robot’s left, and the positive Z-axis points upward.
Why does RViz display a robot model with missing or displaced links?
Missing or misplaced links in RViz typically indicate that the robot_state_publisher node is not receiving joint position messages from joint_state_publisher, or that the fixed frame in RViz does not match the root link declared in the URDF. In addition, if mesh files fail to render, verify that the 3D asset path exists in the active workspace and that the geometry tag specifies valid scaling factors.
Sources
- Open Source Robotics Foundation. (2026). URDF Overview and XML Specification. ROS Wiki. http://wiki.ros.org/urdf
- Open Source Robotics Foundation. (2026). URDF Link XML Specification. ROS Wiki. http://wiki.ros.org/urdf/XML/link
- Open Source Robotics Foundation. (2026). URDF Joint XML Specification. ROS Wiki. http://wiki.ros.org/urdf/XML/joint
- Open Robotics. (2026). URDF Tutorials: Building a Visual Robot Model with URDF from Scratch. ROS 2 Documentation. https://docs.ros.org/en/rolling/tutorials/intermediate/urdf/urdf-overview.html
- Open Robotics. (2026). urdfdom: Unified Robot Description Format DOM and Parser Tools. GitHub Repository. https://github.com/ros/urdfdom
