{"id":8513,"library":"pyrealsense2","title":"Python Wrapper for Intel RealSense SDK 2.0","description":"pyrealsense2 is the official Python wrapper for the Intel RealSense SDK 2.0, providing Python bindings to access the full capabilities of Intel RealSense depth and tracking cameras. It is built on top of the C++ librealsense library. The current version is 2.57.7.10387, and the library maintains an active release cadence with updates typically occurring every few months or as new SDK features and bug fixes are introduced.","status":"active","version":"2.57.7.10387","language":"en","source_language":"en","source_url":"https://github.com/IntelRealSense/librealsense","tags":["realsense","intel","camera","depth-camera","robotics","computer-vision","3d","sensor"],"install":[{"cmd":"pip install pyrealsense2","lang":"bash","label":"Stable Release"}],"dependencies":[{"reason":"pyrealsense2 is a wrapper around the C++ Intel RealSense SDK (librealsense2). It is often required to be installed on the system, especially for source builds or specific environments like ARM/Raspberry Pi.","package":"librealsense2","optional":false},{"reason":"Commonly used for array manipulation of image data received from the camera.","package":"numpy","optional":true},{"reason":"Frequently used for image processing and visualization of RealSense camera streams.","package":"opencv-python","optional":true}],"imports":[{"note":"The standard and recommended import alias for the library.","symbol":"rs","correct":"import pyrealsense2 as rs"}],"quickstart":{"code":"import pyrealsense2 as rs\n\npipe = rs.pipeline()\nprofile = pipe.start()\n\ntry:\n    # Acquire frames for 100 iterations\n    for i in range(0, 100):\n        frames = pipe.wait_for_frames()\n        for f in frames:\n            print(f.profile)\nfinally:\n    pipe.stop()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"2.56.4 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions on non-standard x86/x64 architectures"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (hardware limitation)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"No module named pyrealsense2"},{"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).","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).","error":"ERROR: Could not find a version that satisfies the requirement pyrealsense2 (from versions: ) No matching distribution found for pyrealsense2"},{"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.","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.","error":"AttributeError: module 'pyrealsense2' has no attributed 'pipeline'"},{"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()`.","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.","error":"RuntimeError: Frame did not arrive within 5000 (ms)!"}]}