urdf-viz opens a robot description and lets you drive its joints

A viewer for robot descriptions, not a simulator

urdf-viz visualizes a URDF, the Unified Robot Description Format, file, and it is written in Rust. The repository describes it as a URDF viewer that works on Windows, macOS and Linux, and the topic tags give the context: robotics, ROS, inverse kinematics, XACRO and visualization. What it is not is a physics simulator, and the documentation never claims otherwise. It loads the description, draws the links and their meshes, and lets you move the joints. That is a narrower job than a simulator, and for a large class of tasks it is exactly the right one. Before a URDF goes on real hardware, the questions that matter are structural: do the joint axes point the right way, is the origin of each link where you think it is, does the collision geometry sit where you expect, does the tree close correctly. A static viewer answers those questions in seconds, and a full simulator answers them after you have written a controller. The dependency list explains the rest of the design, with urdf-rs doing the loading, k providing the kinematics on top of nalgebra, and kiss3d doing the drawing.

Installing with cargo, and the assimp feature

If you already work in Rust and have cargo installed, the install is a single command.

cargo install urdf-viz

That build covers meshes in .obj, .stl and .dae format, which is what the mesh-loader dependency handles. If your description uses any other mesh format, you need the assimp feature.

cargo install urdf-viz --features assimp

The assimp feature is not free of consequences, and the README is specific about the build requirements. You need cmake, and on Linux, if you have not installed ROS, you may need cmake, xorg-dev and glu to compile assimp-sys and glfw-sys.

sudo apt-get install cmake xorg-dev libglu1-mesa-dev

The Cargo manifest makes the shape of that optionality explicit, with default = [] and assimp pulling in the assimp and assimp-sys crates plus tempfile. The manifest also shows that the project carries a second target, a workspace member at examples/wasm, with wasm-bindgen, web-sys and js-sys dependencies for a browser build, and the non-wasm target pulls in axum, tokio, tower-http and ureq, which is the web interface and the HTTP server you will meet below. If you do not want to compile anything, prebuilt binaries are on the release page for macOS, Linux and Windows, with the Windows one described as a static executable, and there is a Homebrew tap for macOS and Linux.

brew install openrr/tap/urdf-viz

ROS, xacro and the package:// path problem

The usage section explains what the tool needs at runtime, and it is more than a URDF parser. The urdf-viz command needs rosrun and rospack to resolve package:// in a mesh tag, and it uses xacro to convert a .xacro file into a URDF file. That means you source your workspace first, with something like source ~/catkin_ws/devel/setup.bash, before urdf-viz will find the meshes a ROS description refers to. Given a plain URDF, you point the tool at the file.

urdf-viz URDF_FILE.urdf

A .xacro file works too, and it is converted by rosrun xacro xacro inside urdf-viz, so you can pass it directly.

urdf-viz XACRO_FILE.urdf.xacro

If the xacro file takes arguments, they are passed with the --xacro-args option.

urdf-viz XACRO_FILE.urdf.xacro --xacro-args arg1=value arg2=value

There is an escape hatch for the ROS dependency, and it is worth knowing. If there is no package:// in a mesh tag and you do not use xacro, you can skip installing ROS. And if package:// appears but you know the path or URL of the package, you can also skip ROS by replacing the package with the path or URL, a change the README points at an upstream pull request for. The remaining options are documented in the -h output.

urdf-viz -h

Driving the joints from the keyboard

The GUI is driven by keyboard and mouse, and the mapping is short enough to learn in a minute. Press l to reload the URDF from file, which is the key you will use most since it means you can edit the description in an editor and see the result without restarting. Press c to toggle between the collision model and the visual mode, which is the fastest way to spot a collision shape that is wrong for a link. To move a joint, set its angle with the Up and Down keys, or Ctrl plus Drag to move the angle directly, and you change which joint is the target with o and the bracket keys. Press r to set random joints, and z to reset joint positions and the origin. The camera is moved with the mouse, right drag to translate the view camera position, left drag to look around, and scroll to zoom in and out. There is also inverse kinematics, and the documentation is careful to say it handles positions only, with Shift plus Drag for the Y and Z axes, Shift plus Ctrl plus Drag for the X and Z axes, and the comma and full stop keys changing the move target.

An HTTP interface for setting joint angles

The feature that separates this from a plain viewer is the web I/O interface, which lets you set and get joint angles over HTTP and JSON on a default port of 7777, changeable with the -p option. The set endpoint takes a JSON body with names and positions, and the two arrays have to be the same length, though you do not need to list every joint, only a part of them.

{
  "names": ["joint_name1", "joint_name2"],
  "positions": [0.5, -0.1]
}

The example in the documentation posts a shoulder configuration and shows the response.

$ curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"names": ["r_shoulder_yaw", "r_shoulder_pitch"], "positions": [0.8, -0.8]}' http://127.0.0.1:7777/set_joint_positions | jq
{
  "is_ok": true,
  "reason": ""
}

Reading the joint angles back returns the same shape, and the example response lists every joint of the model with its current angle.

$ curl http://127.0.0.1:7777/get_joint_positions | jq

The robot origin can be set and read the same way, with a position and a quaternion, and the documentation notes that the order of the quaternion elements is w, i, j, k.

$ curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"position":[0.2,0.0,0.0],"quaternion":[0.0,0.0,0.0,1.0]}' http://127.0.0.1:7777/set_robot_origin
{"is_ok":true,"reason":""}

You can also fetch the URDF text back from the running process.

curl http://127.0.0.1:7777/get_urdf_text

Since the process is a normal HTTP server on a local port, this is the natural way to script a sweep of joint positions, and it is why the tool is more useful as a development aid than as a viewer.

Where urdf-viz stops, and what it is not for

Three limits. The first is the ROS coupling in practice. The tool says ROS is only needed for package:// resolution and xacro, and the escape hatches are documented, but a real robot description in a ROS workspace usually uses package:// paths, so a ROS environment is the normal case rather than the exception, and that is a heavier dependency than a URDF parser ought to need. The second is scope. There is no physics, no collision response, no sensor model and no controller interface, so a URDF that looks right here can still behave very differently on hardware where gravity, friction and controller limits apply. The inverse kinematics is for positions only, so it will not orient a tool the way you want in all six degrees of freedom. The third is the release picture. The last tagged version is v0.46.1 from 2024-12-24, with v0.46.0 from 2024-09-12 and v0.45.2 from August 2024 before it, and the last push to the repository was on 2026-06-19, so the project is being worked on but the published versions are more than a year and a half old, and the version stays below 1.0. If you need something maintained on a release cycle, take the source and own it. The alternative worth naming is a browser build, because the manifest carries a wasm workspace member with web-sys features for a WebGL rendering context, which points at the same viewer running in a page instead of a native window, though the repository does not describe that path beyond the dependency list.

Editorial conclusion

Adopt urdf-viz if you need to look at a URDF or XACRO description, check that links and collisions behave as intended, and script joint positions from the shell, since the HTTP interface makes that possible without a simulator. Skip it if you need a physics simulation, since the tool renders geometry and computes kinematics but the README describes no dynamics, and skip it if your description relies on package:// mesh paths and you do not want a ROS environment on your machine, because resolving those paths needs rosrun and rospack. Before you start, read the sample.urdf file at the repository root and check the mesh formats in use, since the default build handles .obj, .stl and .dae only.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. openrr/urdf-viz on GitHub
4. README
5. Releases