4.1. Build from Source with UV (Recommended)

This guide explains how to build pyorbbecsdk wheel packages using uv, a fast Python package manager and resolver. The UV-based build system provides significant advantages over traditional pip/venv workflows:

Fast dependency resolution: UV resolves dependencies 10-100x faster than pip
Automatic Python version management: UV can install and manage multiple Python versions
Automatic virtual environments: UV creates and manages isolated environments automatically
Offline support: Build without internet access using cached dependencies
Cross-platform: Unified build process across Linux, macOS, and Windows
Reproducible builds: Consistent environment setup across different machines

💡 Prefer traditional virtual environments?

If you prefer using standard venv, pyenv, or conda instead of UV, see the Virtual Environment Installation Guide for alternative setup instructions.

4.1.1. Prerequisites

4.1.1.1. All Platforms

Install uv: Follow the official uv installation guide

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify uv installation:
```
uv --version
```
Install CMake (3.15.0 or higher):
- Download from CMake official website
- Or install via package manager

Verify Build Environment:

Before building, verify that the required compiler tools are installed:

=== “Linux/macOS”

```bash
# Check CMake version (requires 3.15.0+)
cmake --version

# Check GCC version (requires 7.4.0+)
gcc --version
g++ --version
```

=== “Windows”

```powershell
# Check CMake version
cmake --version

# Check Visual Studio installation
# Option 1: Using vswhere (if installed with VS)
& "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath

# Option 2: Check for cl.exe
Get-Command cl.exe -ErrorAction SilentlyContinue
```

CMake and Visual Studio Version Compatibility (Windows):

Visual Studio Version	Minimum CMake Version
Visual Studio 2019	3.15.0+
Visual Studio 2022	3.20.0+
Visual Studio 2026	4.2.0+

If any command fails, refer to the Platform-Specific Requirements section below.

Clone the repository:

git clone https://github.com/orbbec/pyorbbecsdk.git
cd pyorbbecsdk
git checkout v2-main

4.1.1.2. Platform-Specific Requirements

4.1.1.2.1. Linux

GCC 7.4.0 or higher
Python development headers

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3-dev build-essential

# CentOS/RHEL/Fedora
sudo yum install python3-devel gcc-c++

4.1.1.2.2. macOS

Xcode Command Line Tools
Clang/Clang++ compiler

# Install Xcode Command Line Tools
xcode-select --install

4.1.1.2.3. Windows

Visual Studio 2019 or 2022 with C++ build tools
Windows SDK

4.1.2. Build Scripts

The project provides platform-specific UV build scripts:

Platform	Script
Linux	`scripts/build_whl/build-whl-uv.sh`
macOS	`scripts/build_whl/build-whl-uv-macos.sh`
Windows	`scripts/build_whl/build-whl-uv.ps1`

Note: These scripts are available in the feature/uv_cli branch. To use them, switch to that branch or copy the scripts to your working directory.

4.1.3. Quick Start

4.1.3.1. Linux

# Make the script executable
chmod +x scripts/build_whl/build-whl-uv.sh

# Build for Python 3.10 (default)
./scripts/build_whl/build-whl-uv.sh

# Build for specific Python version
./scripts/build_whl/build-whl-uv.sh 3.11

# Build for multiple Python versions
./scripts/build_whl/build-whl-uv.sh 3.9 3.10 3.11

# Build all supported versions (3.8-3.13)
./scripts/build_whl/build-whl-uv.sh all

4.1.3.2. macOS

# Make the script executable
chmod +x scripts/build_whl/build-whl-uv-macos.sh

# Build for Python 3.10 (default)
./scripts/build_whl/build-whl-uv-macos.sh

# Build for specific Python version
./scripts/build_whl/build-whl-uv-macos.sh 3.11

# Build for multiple Python versions
./scripts/build_whl/build-whl-uv-macos.sh 3.9 3.10 3.11

# Build all supported versions (3.8-3.13)
./scripts/build_whl/build-whl-uv-macos.sh all

4.1.3.3. Windows

# Build for Python 3.10 (default)
.\scripts\build_whl\build-whl-uv.ps1

# Note: The Windows script currently builds configured versions in the script
# Edit $PythonVersions array in the script to change target versions

4.1.4. Script Options

All build scripts support the following command-line options:

Option	Description
`--offline`	Enable offline mode (requires pre-cached dependencies)
`--no-clean`	Skip cleaning build directories before building
`--clean`	Clean build directories before building (default)
`--clean-only`	Only clean build artifacts, don't build
`-h, --help`	Show help message

4.1.4.1. Examples

# Offline build for Python 3.10
./scripts/build_whl/build-whl-uv.sh --offline 3.10

# Clean and build all versions
./scripts/build_whl/build-whl-uv.sh --clean all

# Only clean build artifacts
./scripts/build_whl/build-whl-uv.sh --clean-only

# Build without cleaning (incremental build)
./scripts/build_whl/build-whl-uv.sh --no-clean 3.11

4.1.5. Offline Build

The UV build system supports offline mode, which is useful when building on machines without internet access.

4.1.5.1. Preparing for Offline Build

On a machine with internet access, prepare the offline environment:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/orbbec/pyorbbecsdk.git
cd pyorbbecsdk

# Create virtual environments with pybind11 for each Python version
for ver in 3.8 3.9 3.10 3.11 3.12 3.13; do
    uv venv venv${ver//./} --python $ver
    uv pip install pybind11 -e . --python venv${ver//./}/bin/python
done

Copy the entire project directory (including the venv* directories) to the offline machine.
Run the offline build:

./scripts/build_whl/build-whl-uv.sh --offline 3.10

4.1.5.2. How Offline Mode Works

When --offline is specified:

The script uses local pybind11 from the venv* directories
UV operates in offline mode (UV_OFFLINE=1)
No network requests are made during the build

4.1.6. Build Output

After successful build, wheel packages are located in:

pyorbbecsdk/
└── wheel/
    ├── pyorbbecsdk2-2.0.XX-cp38-cp38-linux_x86_64.whl
    ├── pyorbbecsdk2-2.0.XX-cp39-cp39-linux_x86_64.whl
    ├── pyorbbecsdk2-2.0.XX-cp310-cp310-linux_x86_64.whl
    └── ...

4.1.6.1. Installing the Wheel

# Install the wheel package
pip install wheel/pyorbbecsdk2-2.0.XX-cp310-cp310-linux_x86_64.whl

# Verify installation
pip show pyorbbecsdk2 | grep Version

4.1.6.2. Generate Type Stubs (Optional but Recommended)

To generate .pyi type stub files for IDE autocomplete support:

# Activate your virtual environment
source orbbec_env/bin/activate  # Linux/macOS
# .\orbbec_env\Scripts\Activate.ps1  # Windows PowerShell

# Install pybind11-stubgen
pip install pybind11-stubgen

# Generate pyi file
pybind11-stubgen pyorbbecsdk -o .

# Fix the generated pyi file
python scripts/fix_pyi.py pyorbbecsdk.pyi

# Copy the fixed pyi file to the package directory
# (find the package path using pip show)
cp pyorbbecsdk.pyi $(python -c "import pyorbbecsdk, os; print(os.path.dirname(pyorbbecsdk.__file__))")/

4.1.7. Build Process Details

The build scripts perform the following steps:

Parse Arguments: Process command-line options and Python versions
Architecture Detection: Detect system architecture (x86_64, arm64)
Environment Setup: Configure library paths for the SDK
Cleanup (optional): Remove previous build artifacts
Per-Version Build:
- Resolve Python interpreter using UV
- Resolve pybind11 CMake directory
- Configure with CMake (using appropriate compiler)
- Build and install targets
- Copy runtime files (examples, config, stubs)
- Build wheel package using uv build
- Repair wheel with auditwheel (Linux only)
Final Cleanup: Remove temporary build directories

4.1.7.1. Key Differences by Platform

Feature	Linux	macOS	Windows
Compiler	GCC/G++	Clang/Clang++	MSVC
Library Path	`LD_LIBRARY_PATH`	`DYLD_LIBRARY_PATH`	PATH
Architecture	x86_64, arm64	arm64	x64
Wheel Repair	auditwheel	None needed	None needed
Deployment Target	-	macOS 13.0+	-

4.1.8. Troubleshooting

4.1.8.1. Common Issues

4.1.8.1.1. “uv: command not found”

Solution: Ensure uv is installed and in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

4.1.8.1.2. “CMake configuration failed”

Solution: Verify CMake version and Python development headers:

# Check CMake version
cmake --version

# Install Python development headers (Linux)
sudo apt-get install python3-dev

4.1.8.1.3. “pybind11 not found” (Offline mode)

Solution: Ensure virtual environments are set up correctly:

# Create venv with pybind11
uv venv venv310 --python 3.10
uv pip install pybind11 --python venv310/bin/python

4.1.8.1.4. “Permission denied” on macOS

Solution: Fix library permissions:

chmod +x scripts/build_whl/build-whl-uv-macos.sh

4.1.8.1.5. Build fails on Windows with “Visual Studio not found”

Solution: Ensure Visual Studio 2019 or 2022 with C++ tools is installed, or specify the generator explicitly:

# In the PowerShell script, modify the cmake command
cmake -G "Visual Studio 17 2022" -A x64 ...

4.1.8.2. Cleaning Build Artifacts

If you encounter persistent build issues, perform a full clean:

# Using the script
./scripts/build_whl/build-whl-uv.sh --clean-only

# Manual cleanup
rm -rf build build_* dist install wheel src/*.egg-info

4.1.9. Advanced Usage

4.1.9.1. Customizing Python Versions

Edit the build script to change default Python versions:

# In scripts/build_whl/build-whl-uv.sh, modify:
PYTHON_VERSIONS=("3.10" "3.11")  # Your desired versions

4.1.9.2. Parallel Builds

The scripts automatically use all available CPU cores:

Linux: make -j$(nproc)
macOS: make -j$(sysctl -n hw.ncpu)
Windows: cmake --build --parallel

4.1.9.3. Environment Variables

Variable	Description
`UV_LINK_MODE`	Set to `copy` for compatibility (default in scripts)
`UV_OFFLINE`	Set to `1` to enable offline mode
`MACOSX_DEPLOYMENT_TARGET`	Minimum macOS version (default: 13.0)

4.1.10. Comparison with Traditional Build

Feature	Traditional (pip/venv)	UV Build
Python Installation	Manual	Automatic
Dependency Resolution	pip	UV (faster)
Virtual Environment	Manual	Automatic
Offline Support	Limited	Full support
Cross-Platform	Different commands	Unified scripts
Build Time	Slower	Faster

4.1.11. Next Steps

After building the wheel:

Install the wheel: pip install wheel/*.whl
Set up environment: Run scripts/env_setup/install_udev_rules.sh (Linux)
Run examples: See examples/ directory for sample code
Refer to registration script: See registration_script.md for device setup

4.1.12. See Also

Install the Package - Installing pre-built wheels
Build from Source - Traditional CMake build method
UV Documentation