The pyorbbecsdk build step refuses to compile anything

The package name, the import name, and the branch all differ

Three names are in play, and a new user meets all three.

The repository is pyorbbecsdk. The distribution on the package index is pyorbbecsdk2, which is what you install. The module you import is pyorbbecsdk, without the suffix.

from pyorbbecsdk import *

pipeline = Pipeline()
pipeline.start()                        # uses default config from OrbbecSDKConfig.xml
frames = pipeline.wait_for_frames(1000) # get synchronized Color + Depth frames

So an install command naming the suffixed distribution followed by an import naming the unsuffixed module is the expected path, not a mistake.

The branch is a fourth wrinkle. The default branch is the version two line, and the legacy version one line lives on the branch called main. That inversion catches people who clone and assume the default is stable.

The split matters because the two lines support different cameras. Three specific legacy models, including two Astra variants and a Gemini XL, are documented as requiring the older branch rather than the current one.

The build command copies files and fails loudly when they are missing

The packaging code is the most informative file in the repository, and it says the native library is never compiled by Python.

There is a custom extension class declared with an empty source list. A source list is what a compiler consumes, and it is empty here, so nothing is compiled. The build directory is supplied separately as a library path.

Then a custom build command runs. Its first act is to check that the library directory exists and is not empty. If it is missing or empty, it raises a file-not-found error whose message tells you to compile with CMake first.

That is the whole design: the Python package expects to find a native library someone else built, and it refuses rather than silently producing an importable module that fails at runtime.

After the check passes it copies every file from the library directory into the extension output directory, and on macOS it repairs the runtime search path for the dynamic library dependencies that the copy would otherwise break.

The repository layout matches the design: a build definition at the root with a CMake directory beside it, a native SDK directory, the binding sources, generated stubs, and a build guide that names a Python package manager as the tool for building from source.

Python 3.8 is supported and has no Linux wheel

The declared floor is Python 3.8, and the oldest supported interpreter is the one with a packaging hole.

The install note for Linux says the package index provides no pre-built wheels for Python 3.8 on either architecture, and gives two ways out: download the wheel from the release page, or build from source.

That makes the compatibility table uneven in an easy-to-miss way. Windows users on 3.8 get a wheel. Linux users on 3.8 do not, and have to fetch a release artifact or compile. Anyone choosing an interpreter for a new deployment will normally pick a current one, so this bites mainly on long-lived environments.

The pre-built wheels are advertised as requiring no compilation for Windows x64, Linux x64, and ARM64, which is a genuinely good default position for a package that wraps native code.

The install path also carries a warning about modern systems, which restrict installation into the system interpreter, and recommends a virtual environment, showing the three activation commands for Linux, macOS, and Windows. The documentation goes further and links a virtual environment guide covering three separate environment managers.

The two points compose badly for a 3.8 Linux user: no wheel, and an installer that wants to write to a protected location.

The requirements file claims to be synced and is not

Two files describe the runtime dependencies, and they disagree.

The requirements file opens with a comment saying its contents are synced from the package metadata. What follows is a readable version with a comment per dependency: the video library, NumPy, an OpenCV build, a game and windowing library for visualization, a point cloud library marked for Python 3.8 through 3.11, an input library, and two macOS-specific packages marked for Python below 3.9.

The package metadata expresses the same intent through environment markers, and the differences are not cosmetic.

The video library is pinned to one exact version below Python 3.13 and a different exact version at 3.13 and above. The requirements file lists a single lower bound with no version marker at all, so installing from it gives you whichever release the resolver picks.

NumPy is the same pattern. The metadata caps it below 2.0 for Python 3.8 to 3.11 and requires 2.1 or newer from 3.12. The requirements file says one lower bound for everything, which on a modern interpreter silently permits a NumPy release the metadata would have excluded.

The file also lists the build-time dependencies, the binding generator and its global variant, inside what otherwise looks like a runtime list, and comments out the development group rather than omitting it.

Six declared dependencies resolve into up to ten installed packages

The dependency list looks short until the environment markers are unpacked.

Two entries are unconditional: an OpenCV build for computer vision, and a game and windowing library, which is there for visualization rather than for images.

Three are split by Python version. The video library changes version at 3.13. NumPy changes major version at 3.12. And the point cloud library is installed only between 3.8 and 3.11, which means a Python 3.12 environment has no point cloud support from this package at all.

The input library is where the list gets tangled. It appears in three separate marker forms: every platform except macOS, macOS at Python 3.9 and above, and macOS below 3.9. The last case exists because on macOS the input library needs the Objective-C bridge, which in turn requires Python 3.9 or newer, so older macOS interpreters get an older pinned bridge package and a newer pinned windowing package instead.

Those markers are mutually exclusive, so the same package is only installed once. But the duplication is a maintenance surface: changing the minimum macOS version means editing three lines and two pinned versions in step.

The environment step is a script that asks for administrator rights

Installing the package is not enough, and the second step explains why.

There is a one-time operating-system level configuration for the camera metadata and the device rules that let a non-root process claim the device. On Windows the script requests administrator rights automatically; on Linux it requests elevated permissions.

It can be run from a checkout or from the installed package. The second form resolves the package directory at runtime and points the interpreter at a script inside it, so you can re-run the setup without finding the source tree again.

The device rules are the substantive part. Without them, the library loads and the camera is invisible, and the failure looks like a detection problem rather than a permissions one.

The README also mentions an automated firmware update in its contents list and a firmware update sample in the beginner set, alongside the note that most new devices ship with compatible firmware pre-installed and work without intervention. That split matters: firmware is mostly a non-event on current hardware and a project on older hardware.

Thirty-five samples across four levels, and a protocol change on the horizon

The examples directory is organised by difficulty rather than by feature, and the README says so explicitly.

The first level is a single zero-configuration viewer. The second is a beginner set covering the obvious ground: opening the camera, depth visualisation, alignment, calibration, point clouds, multiple streams, the inertial unit, network cameras, and firmware update.

The third level is where the interesting scripts live: recording and playback, device control, filter chains, high dynamic range, presets, depth work modes, multi-device synchronisation, coordinate transforms, and a high-performance pipeline variant.

The fourth level splits into applications, with object detection and a depth overlay plus an interactive depth ruler, and a separate LiDAR set. Alongside them sit a script that runs everything and a shared utility module.

There is also a device-level change to plan for. From October 2025, at a named SDK version, devices speaking the OpenNI protocol are moved to UVC, with an upgrade document linked. And three legacy camera models are documented as requiring the older branch.

Those two facts together are the compatibility work: which branch, and which protocol the firmware expects.

Editorial conclusion

pyorbbecsdk suits a developer with an Orbbec camera on Python 3.12 or newer on Windows, Linux, or ARM64, where a prebuilt wheel covers the whole stack including the native library. It does not suit someone on Python 3.8 with Linux, where no wheel is published for that combination, or anyone who expects the build to compile the core for them. Before you start, check your interpreter against the wheel matrix, run the one-time environment setup script for the operating system metadata, and read the protocol change that moves OpenNI devices to UVC.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. orbbec/pyorbbecsdk on GitHub
3. Project website
4. README
5. Releases