TL;DR:
URDF (Unified Robot Description Format) is an XML file that describes a robot as links connected by joints.
Each joint places a child frame relative to its parent, so software can compute where every part is.
Links have a visual shape for display and a simpler collision shape for physics and planning.
Your arm planner needs to know how long each segment is and which way each joint turns. The simulator needs the mass of each part. The display needs a shape to draw. Instead of hard-coding this in three places, you write it once in a robot description, and every tool reads the same file.
What a URDF does on a robot
URDF is an XML format used widely in ROS. It describes a robot as a tree. The parts are links, the rigid bodies, and the connections are joints. Every joint has one parent link and one child link, and a link can have only one parent, so the structure is a tree with no loops.
Software can then answer questions such as where the gripper is when the shoulder is at 30 degrees. That calculation is forward kinematics, and it depends entirely on the numbers in this file.
Links, joints and frames
Every link has its own coordinate frame. A joint's origin tag says where the child frame sits relative to the parent frame: a translation xyz in meters and a rotation rpy (roll, pitch, yaw) in radians. The axis tag says which direction the joint turns or slides, written in the joint's own frame.
Joint types you meet first are revolute (turns within limits), continuous (turns without limits, like a wheel), prismatic (slides), and fixed (rigidly attached, like a sensor bolted on). Revolute joints need limit values for the lower and upper angle, plus effort and velocity limits.
Worked example: a two-link arm in URDF
Build a vertical-plane arm: a fixed base, a 0.30 m upper arm and a 0.20 m forearm, each joint turning about the y axis. The origin is at the base, with x forward and z up.
<robot name="two_link_arm">
<link name="base_link"/>
<link name="upper_arm">
<visual>
<origin xyz="0.15 0 0"/>
<geometry><box size="0.30 0.04 0.04"/></geometry>
</visual>
<collision>
<origin xyz="0.15 0 0"/>
<geometry><box size="0.30 0.04 0.04"/></geometry>
</collision>
<inertial>
<mass value="0.3"/>
<inertia ixx="0.0001" iyy="0.0002" izz="0.0002" ixy="0" ixz="0" iyz="0"/>
</inertial>
</link>
<link name="forearm">
<visual>
<origin xyz="0.10 0 0"/>
<geometry><box size="0.20 0.03 0.03"/></geometry>
</visual>
<collision>
<origin xyz="0.10 0 0"/>
<geometry><box size="0.20 0.03 0.03"/></geometry>
</collision>
<inertial>
<mass value="0.15"/>
<inertia ixx="0.00005" iyy="0.0001" izz="0.0001" ixy="0" ixz="0" iyz="0"/>
</inertial>
</link>
<joint name="shoulder" type="revolute">
<parent link="base_link"/>
<child link="upper_arm"/>
<origin xyz="0 0 0.05"/>
<axis xyz="0 1 0"/>
<limit lower="-1.57" upper="1.57" effort="5" velocity="1.0"/>
</joint>
<joint name="elbow" type="revolute">
<parent link="upper_arm"/>
<child link="forearm"/>
<origin xyz="0.30 0 0"/>
<axis xyz="0 1 0"/>
<limit lower="0" upper="2.35" effort="3" velocity="1.0"/>
</joint>
</robot>Read it as a chain. The shoulder frame sits 0.05 m above the base. The upper arm's box is centred 0.15 m along x from its frame, so it spans 0 to 0.30 m. The elbow frame is 0.30 m along the upper arm, exactly at the end of that box, and the forearm's box spans the next 0.20 m.
Check it with the arm straight out, both joints at 0. The tip is at x = 0.30 + 0.20 = 0.50 m, z = 0.05 m. Now bend the elbow by 90 degrees. About the y axis, a positive rotation tips +x toward −z, so the forearm points down and the tip lands at x = 0.30, z = 0.05 − 0.20 = −0.15 m. The elbow limit of 2.35 rad is about 135 degrees, since 2.35 × 180 / π ≈ 134.6°.
The inertia numbers above are small made-up values for a toy. For a real arm, take them from CAD or from formulas. A rough bar value is m·L² / 12 about its centre: for the upper arm, 0.3 × 0.30² / 12 = 0.00225 kg·m² about the y axis. That is far larger than the 0.0002 above, which shows why copying placeholder inertias into a real simulation makes it behave oddly.
Visual versus collision geometry
Each link can have a visual shape, used for display and as detailed as you like, and a collision shape, used by physics engines and motion planners. Collision checks run thousands of times, so the collision shape should be simple: boxes, cylinders, spheres or a few convex pieces. A detailed mesh there makes everything slower.
Make the collision shape slightly bigger than the real part if you want a safety margin. Make sure it is never smaller where something could hit, or the planner will think a collision is free.
Where it goes wrong
Units. Lengths are meters, angles are radians, mass is kilograms. Millimeters pasted in from CAD make a robot 1000 times too large.
Wrong axis or origin. A joint that turns the wrong way is almost always a sign or axis error.
Missing inertia. A link with zero or placeholder inertia may be unstable in simulation.
Too-detailed collision meshes. Planning becomes slow.
Limits that do not match hardware. If the file allows more travel than the real joint, a planned motion can crash the arm into its own stops.
Safety: Match joint limits and effort values to the real hardware before sending planned motions to a physical arm. Keep clear of the arm's reach on first runs and keep the emergency stop in hand.
How real robots use it
Tools turn the URDF into a live tree of frames, so every link's position is available while the robot moves. Simulators load it to create the robot, and visualizers draw it. How those frames convert positions between them is covered in coordinate frames and transforms. Many robots generate their URDF from a more compact macro format and check it with tools before use.
Try it yourself
Copy the arm above into a file and load it in any URDF viewer. Move the two joints with sliders and compare the tip position you see with the numbers you calculated by hand. Then change the forearm length to 0.25 m in one place and see which other numbers you must change to keep the model consistent.
Frequently asked questions
Can URDF describe a closed loop, like a four-bar linkage?
Not directly, because it is a tree. Other formats or extra constraints in the simulator are used for loops.
Is URDF the only robot description format?
No. Simulators have their own formats, and SDF is a common one. URDF is the one most ROS tools read.
Get started
