What Is URDF? A Practical Guide to Robot Description Files

URDF (Unified Robot Description Format) is an XML format for describing the geometry and organization of one robot in ROS. A URDF model connects rigid link elements with joint elements and can attach visual, collision, and inertial properties to each link. ROS tools use the resulting tree for visualization, transforms, planning, and simulation integration.

What does a URDF file contain?

Every URDF starts with one robot root element. Its links represent rigid bodies; its joints describe the relationship and permitted motion between a parent link and a child link. A valid robot model forms a tree, with one root link and no closed kinematic loops in the plain URDF structure.

<?xml version="1.0"?>
<robot name="two_link_robot">
  <link name="base_link" />
  <link name="arm_link" />

  <joint name="arm_joint" type="revolute">
    <parent link="base_link" />
    <child link="arm_link" />
    <origin xyz="0 0 0.3" rpy="0 0 0" />
    <axis xyz="0 0 1" />
    <limit lower="-1.57" upper="1.57" effort="20" velocity="1" />
  </joint>
</robot>

What are links and joints?

A link is a rigid part such as a chassis, wheel, forearm, or sensor housing. A joint connects two links. Common joint types include fixed, revolute, continuous, prismatic, planar, and floating. Motion joints usually need an axis and appropriate limits.

Why are visual, collision, and inertial tags separate?

• Visual geometry controls what the link looks like in tools such as RViz.
• Collision geometry is used for contact and collision checks. Simpler shapes can be faster and more stable than a detailed render mesh.
• Inertial data supplies mass, center of mass, and the inertia matrix needed by physics engines.

A model can render correctly while still behaving badly in simulation if collision or inertial values are missing or unrealistic. The official ROS tutorial specifically covers adding these physical properties after the visual model is working.

How does ROS 2 use URDF?

The robot_state_publisher package consumes the robot description and joint states, then publishes the resulting transforms to /tf and/tf_static. Other tools can use the same robot_description for visualization or planning. A URDF alone does not provide controllers or real sensor data; those are separate parts of the ROS system.

What is the difference between URDF and Xacro?

URDF is the XML robot description consumed by ROS tools. Xacro is a macro language that can generate URDF. It adds variables, reusable macros, math, and conditional sections, which makes large robot families easier to maintain. When a repository contains a.xacro file, inspect its launch or build instructions to see how it is expanded into the final robot description.

What is the difference between URDF and SDF?

URDF is centered on one robot model and ROS workflows. SDFormat can represent models, actors, lights, physics, plugins, and complete worlds. Gazebo's official documentation notes that SDF can describe a world with multiple robot models, while URDF describes one robot model; Gazebo can convert supported URDF content internally when spawning a robot.

How should you evaluate a downloaded URDF model?

1. Read the upstream repository's README and license.
2. Check the supported ROS distribution and required packages.
3. Resolve all package:// mesh and texture paths.
4. Expand Xacro with the arguments documented by the maintainer.
5. Open the model in RViz before adding controllers or physics.
6. Check joint axes, limits, collision shapes, masses, and inertia tensors.
7. Follow simulator-specific instructions instead of assuming one model works everywhere.

Where can you find URDF robot models?

Start with the robot manufacturer or active upstream ROS package whenever possible. URDF Hub links to a small curated set of those public repositories; it does not mirror or relicense their files. Browse the featured model sources, then verify the repository branch, license, and compatibility before use.

What should you learn next?

Follow the official ROS 2 sequence: build a visual model, add movable joints, add collision and inertial properties, and then use Xacro to reduce repetition. After that, connect the model to robot_state_publisher or follow the current Gazebo guide for spawning URDF.

• ROS 2 URDF tutorials
• robot_state_publisher documentation
• Gazebo: spawn a URDF model
• SDFormat specification

Sources checked July 20, 2026. ROS and Gazebo documentation changes by release; verify the instructions for the distribution and simulator version you use.