Python Wrapper for Intel RealSense SDK 2.0

Common errors

• No module named pyrealsense2

  cause The `pyrealsense2` package or its underlying `librealsense` C++ library was not installed correctly or is not discoverable in the Python environment. This is common on ARM devices (e.g., Raspberry Pi) or macOS.
  fix Verify installation. On ARM, building from source with Python bindings is often necessary. On macOS, try `pip install pyrealsense2 -f https://github.com/cansik/pyrealsense2-macosx/releases` if standard pip fails. Ensure the Python version matches the installed wheel or source build targets. If building from source, ensure `.so` files are in the Python path or copied to the script's directory.

• ERROR: Could not find a version that satisfies the requirement pyrealsense2 (from versions: ) No matching distribution found for pyrealsense2

  cause Pip could not find a pre-built wheel package for your specific operating system and Python version/architecture (e.g., ARM, older macOS, or unsupported Python 3.x version).
  fix This typically indicates a need to build `pyrealsense2` from source, often after building the `librealsense` C++ SDK from source, with Python bindings enabled. Check the official `librealsense` GitHub for detailed build instructions for your platform. Also, verify that your Python version is supported (currently >=3.9).

• AttributeError: module 'pyrealsense2' has no attributed 'pipeline'

  cause This error often occurs when the `pyrealsense2` library is either incompletely installed, corrupted, or when there's an issue with the underlying `librealsense` library. It can also occur if attempting to use an incorrect import pattern, though `import pyrealsense2 as rs` is standard.
  fix Reinstall `pyrealsense2` and ensure that `librealsense` is correctly installed on your system. If building from source, ensure all dependencies are met and the build completes without errors. Verify that `import pyrealsense2 as rs` is used correctly.

• RuntimeError: Frame did not arrive within 5000 (ms)!

  cause The camera is connected but not actively streaming frames, or there's a problem with the USB connection (e.g., insufficient bandwidth on USB 2.0, loose cable), or the camera is in an error state.
  fix Check the physical USB connection, ensuring a USB 3.0 port and cable are used. Restart the camera (unplug/replug). Verify camera is detected by `rs-enumerate-devices` (if SDK is installed). Ensure that `pipeline.start(config)` is correctly configured and executed before `pipeline.wait_for_frames()`.

Warnings

• breaking Specific RealSense camera models (e.g., D457) might require a firmware (FW) and MIPI driver upgrade for full compatibility with certain pyrealsense2 versions, especially for new features like IR stream metadata support. Older firmware might lead to unexpected behavior or limited functionality.
  Fix: Check Intel's official RealSense documentation for your camera model's latest firmware and driver updates, and apply them. Ensure your operating system's kernel and drivers are also up-to-date if building from source.
• gotcha Direct `pip install pyrealsense2` often fails on ARM-based devices (e.g., Raspberry Pi) or some macOS systems, resulting in 'No matching distribution found' or 'No module named pyrealsense2' errors. This is because pre-built wheels might not be available or compatible.
  Fix: For ARM/Raspberry Pi, a source build of librealsense with Python bindings is generally required. For macOS, ensure you have a supported Python version and try `pip install pyrealsense2 -f https://github.com/cansik/pyrealsense2-macosx/releases` if the standard pip install fails, or build from source if necessary.
• gotcha Using a USB 2.0 cable with RealSense cameras can severely limit bandwidth, leading to dropped frames, lower resolutions, or 'bad argument' errors when attempting to stream high-resolution or multiple streams. The camera might connect but not provide expected data.
  Fix: Always use a high-quality USB 3.0 compatible cable and connect to a USB 3.0 port on your computer for optimal performance and reliable data streams.
• gotcha Users have reported issues when integrating pyrealsense2 with multithreading, particularly when processing frames in separate threads. This can manifest as unexpected errors or application freezes, potentially related to Python's GIL or internal SDK threading models.
  Fix: Carefully manage frame acquisition and processing in multithreaded applications. Consider using queues with limited sizes, and ensure proper synchronization. If possible, perform heavy processing in separate processes rather than threads, or offload processing to dedicated hardware/GPUs.

Install

• pip install pyrealsense2 Stable Release

Imports

• rs

  import pyrealsense2 as rs

  The standard and recommended import alias for the library.

Quickstart

This quickstart initializes a RealSense pipeline, starts streaming, waits for 100 frames, prints the profile of each received frame, and then stops the pipeline. It demonstrates the basic lifecycle of interacting with a RealSense camera.

import pyrealsense2 as rs

pipe = rs.pipeline()
profile = pipe.start()

try:
    # Acquire frames for 100 iterations
    for i in range(0, 100):
        frames = pipe.wait_for_frames()
        for f in frames:
            print(f.profile)
finally:
    pipe.stop()