Install & Compatibility
Where this runs
tested against v2.58.2.10647 · 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
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.1s · import 0.000s · 54MB
51MB installed
● package 51MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
rs
✓ import pyrealsense2 as rs
The standard and recommended import alias for the library.
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()
Debug
Known issues
breakingSpecific 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.fixCheck 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.
affects: 2.56.4 and later
gotchaDirect `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.fixFor 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.
affects: All versions on non-standard x86/x64 architectures
gotchaUsing 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.fixAlways 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.
affects: All versions (hardware limitation)
gotchaUsers 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.fixCarefully 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.
affects: All versions
Errors
Common errors & fixes
No module named pyrealsense2
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.
fixVerify 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
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).
fixThis 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'
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.
fixReinstall `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)!
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.
fixCheck 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()`.
Upgrade
Version history
2.58.2.10647latest on PyPI · released Jun 14, 2026
Audit
Dependencies
librealsense2requiredpyrealsense2 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.
numpyoptionalCommonly used for array manipulation of image data received from the camera.
opencv-pythonoptionalFrequently used for image processing and visualization of RealSense camera streams.