yourdfpy

library0.0.60pypypi✓ verified 26d ago

yourdfpy is a Python library designed for simpler and easier loading, manipulation, saving, and visualization of URDF (Universal Robot Description Format) files. It is currently at version 0.0.60 and is actively maintained with frequent micro-releases addressing bug fixes and minor improvements.

serialization data

pip install yourdfpy

github ↗package ↗

INSTALL

IMPORT

SIG · YOURDFPY

yourdfpy

serializationpythonv0.0.60

Install

13.7s avg

Import

2716ms

Disk

372MB

Pass rate

9/ 10

Env Coverage9 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.0.60 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 13.8s

py 3.11

✓ —

✓ 13.6s

py 3.12

✓ —

✓ 13.1s

py 3.13

✓ —

✓ 12.7s

py 3.9

✕ build_error

✓ 15.5s

372MB installed

● package 372MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

URDF

✓ from yourdfpy import URDF

✗ import yourdfpy.URDF

The primary class for loading and managing URDF models. Direct import is standard.

urdf_to_scene

✓ from yourdfpy.visualization import urdf_to_scene

Function to convert a URDF object to a trimesh.Scene for advanced visualization or manipulation.

This quickstart demonstrates how to load a simple URDF model (either programmatically or from a file), update its joint configuration, and visualize it using the built-in interactive viewer. Ensure you have a graphics environment capable of running pyglet for the `robot.show()` method.

from yourdfpy import URDF, primitives # Create a simple demo URDF programmatically (e.g., a multi-link chain) robot = primitives.create_urdf(joints=['prismatic', 'revolute', 'fixed']) # Alternatively, load from a file (replace 'path/to/robot.urdf' with your file) # from yourdfpy import URDF # robot = URDF.load('path/to/robot.urdf') # You can update joint configurations robot.update_cfg({'prismatic_0': 0.5, 'revolute_1': 0.785}) # move prismatic joint by 0.5 and revolute by 45 degrees # Display the robot model in an interactive viewer robot.show() # Access robot properties print(f"Robot name: {robot.name}") print(f"Number of joints: {len(robot.joint_map)}") print(f"Current configuration: {robot.config}")

Debug

Known issues

gotchaThe interactive visualization (`.show()`) relies on `pyglet`, which may require specific OpenGL drivers or X server configurations, especially in headless environments or on certain operating systems (e.g., WSL, virtual machines).

fix

Ensure your environment meets pyglet's graphical requirements. For headless environments, consider using `yourdfpy.visualization.urdf_to_scene` to get a `trimesh.Scene` object and render it with an alternative backend or export to an image.

affects: All versions

gotchaWhen loading URDF files with relative paths to meshes or other assets, `yourdfpy` expects the assets to be resolvable relative to the URDF file's location or through a configured filename handler. Incorrect paths are a common source of 'mesh not found' errors.

fix

Ensure your URDF file and its associated mesh files (e.g., .stl, .obj) are correctly placed relative to each other, or pass an absolute path to the URDF. For complex asset structures, consider implementing a custom `filename_handler` when loading the URDF (e.g., `URDF.load('robot.urdf', filename_handler=my_handler)`).

affects: All versions

gotchaThe library is still in its `0.0.x` version series, indicating it's pre-1.0. While API stability is generally good, minor updates (`0.0.x` to `0.0.y`) could still introduce subtle behavior changes or require small adjustments, particularly concerning numerical precision or input data types.

fix

Monitor release notes for each update. Pay close attention to changes involving numerical calculations (e.g., NumPy array handling, kinematics) and ensure your input data types align with expected arguments, especially for methods like `update_cfg`.

affects: All 0.0.x versions

gotchaPassing joint configurations for `update_cfg` can be sensitive to the dictionary keys. It expects string keys that exactly match the joint names defined in the URDF. Mismatches will lead to joints not updating as expected.

fix

Always verify joint names in your URDF file or via `robot.joint_map.keys()` and ensure these exact strings are used as keys in the configuration dictionary passed to `update_cfg`.

affects: All versions (specifically noted in v0.0.60 fix)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'yourdfpy'

The `yourdfpy` library has not been installed in your current Python environment.

fix

Install the library using pip: `pip install yourdfpy`

FileNotFoundError: [Errno 2] No such file or directory: 'path/to/your/robot.urdf'

The specified path to the URDF file is incorrect, or the file does not exist at the given location.

fix

Verify the file path and ensure the URDF file is present. Use an absolute path or ensure the relative path is correct from your script's execution directory, for example: `robot = URDF.load('your_robot_model.urdf')`

ModuleNotFoundError: No module named 'pyrender'

The `pyrender` library, an optional dependency required for `yourdfpy`'s visualization features (like `robot.show()`), is not installed.

fix

Install the display dependencies for `yourdfpy` (which includes `pyrender` and `trimesh`): `pip install "yourdfpy[display]"`

lxml.etree.XMLSyntaxError: Start tag expected, '<' not found, line 1, column 1

The URDF file provided is not a valid XML document, likely due to malformation, corruption, or being an empty file.

fix

Inspect the URDF file to ensure it's a well-formed XML document, starting with an XML declaration and a root `<robot>` tag. Correct any syntax errors in the XML structure.

AttributeError: 'URDF' object has no attribute 'visualize'

The `visualize` method does not exist for the `URDF` object; the correct method for displaying the robot is `show()`.

fix

Use the correct method name `show()` to visualize the URDF: `robot.show()`

Upgrade

Version history

0.0.60latest on PyPI · released Jan 23, 2026

Audit

Dependencies

trimeshrequiredCore dependency for 3D geometry processing and mesh handling.

numpyrequiredEssential for numerical operations, especially with transformations and joint configurations.

pygletrequiredUsed as the default backend for interactive 3D visualization.

Agent activity

41 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/clemense/yourdfpy ↗

packagehttps://pypi.org/project/yourdfpy/ ↗