2.1. Virtual Environment Installation Guide

Virtual Environments are Recommended for Installing pyorbbecsdk

Modern operating systems (especially macOS and newer Linux distributions) increasingly restrict modifications to the system Python environment. Using virtual environments allows you to:

Avoid permission errors and system protection mechanisms

Prevent package conflicts between different projects

Create reproducible dependency environments

Support multiple Python versions simultaneously

2.1.2. 📊 Tool Selection Guide

Scenario	Recommended Tool	Reason
Quick start, minimal configuration	venv	Built into Python, no installation needed
Multiple projects, multiple Python versions	pyenv + venv	Flexible Python version management
Data science, complex dependencies	conda	Excellent at handling non-Python dependencies
CI/CD automation	venv	Lightweight, standard tool

2.1.3. Quick Start

2.1.3.1. Linux / macOS (venv)

# Create virtual environment
python3 -m venv orbbec_env

# Activate environment
source orbbec_env/bin/activate

# Install SDK
pip install --upgrade pyorbbecsdk2

# Verify installation
pip show pyorbbecsdk2 | grep Version

2.1.3.2. Windows (venv)

# Create virtual environment
python -m venv orbbec_env

# Activate environment (PowerShell)
.\orbbec_env\Scripts\Activate.ps1

# Install SDK
pip install --upgrade pyorbbecsdk2

# Verify installation
pip show pyorbbecsdk2 | findstr Version

2.1.4. 1. Using venv (Recommended for Beginners)

venv is a virtual environment tool included in the Python standard library - no additional installation required.

2.1.4.1. 1.1 Check Python Version

Ensure Python 3.8 or higher is installed:

Linux/macOS:

python3 --version

Windows:

python --version

2.1.4.2. 1.2 Create Virtual Environment

Create a virtual environment in your project directory:

All Platforms:

# Linux/macOS/Windows universal
python3 -m venv orbbec_env

# Windows if python3 command is not available, use:
python -m venv orbbec_env

Naming suggestion: Use orbbec_env or .venv as the environment name

2.1.4.3. 1.3 Activate Virtual Environment

Linux/macOS:

source orbbec_env/bin/activate

Windows (CMD):

orbbec_env\Scripts\activate.bat

Windows (PowerShell):

.\orbbec_env\Scripts\Activate.ps1

When activated, the command prompt will display the environment name:

(orbbec_env) user@computer:~$

2.1.4.4. 1.4 Install pyorbbecsdk2

Install in the activated virtual environment:

pip install --upgrade pyorbbecsdk2

2.1.4.5. 1.5 Verify Installation

pip show pyorbbecsdk2

Expected output:

Name: pyorbbecsdk2
Version: 2.0.16
...

2.1.4.6. 1.6 Run Examples

# Test import
python -c "import pyorbbecsdk; print('Import successful')"

# Find example code location
python -c "import pyorbbecsdk; import os; print(os.path.dirname(pyorbbecsdk.__file__))"

2.1.4.7. 1.7 Deactivate Virtual Environment

deactivate

2.1.5. 2. Using pyenv (Multiple Python Versions)

pyenv allows you to install and manage multiple Python versions on your system, ideal for developers who need to switch between different Python versions.

2.1.5.1. 2.1 Install pyenv

macOS (using Homebrew):

brew install pyenv

Linux:

curl https://pyenv.run | bash

# Add to shell configuration (~/.bashrc or ~/.zshrc)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# Reload configuration
source ~/.bashrc

Verify installation:

pyenv --version

2.1.5.2. 2.2 Install Python 3.10

# View installable versions
pyenv install --list | grep "^  3.10"

# Install Python 3.10.16 (example)
pyenv install 3.10.16

# Set global default version (optional)
pyenv global 3.10.16

2.1.5.3. 2.3 Set Local Python Version in Project Directory

cd your_project_directory
pyenv local 3.10.16

This creates a .python-version file that automatically switches Python versions when entering the directory.

2.1.5.4. 2.4 Create Virtual Environment and Activate

# Create venv using pyenv's Python
python3 -m venv orbbec_env

# Activate
source orbbec_env/bin/activate

2.1.5.5. 2.5 Install pyorbbecsdk2

pip install --upgrade pyorbbecsdk2

2.1.5.6. 2.6 Complete Workflow Example

# Enter project directory
cd ~/projects/orbbec_demo

# Python automatically switches to 3.10.16 (via .python-version)
python --version  # Python 3.10.16

# Activate virtual environment
source orbbec_env/bin/activate

# Run program
python your_script.py

# Exit
deactivate

2.1.6. 3. Using conda (Data Science Users)

conda is the package manager for Anaconda/Miniconda, particularly adept at handling non-Python dependencies.

2.1.6.1. 3.1 Install Miniconda

Download installer:

Linux:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

macOS (Apple Silicon):

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
bash Miniconda3-latest-MacOSX-arm64.sh

Windows: Download and run Miniconda3-latest-Windows-x86_64.exe

2.1.6.2. 3.2 Create conda Environment

# Create Python 3.10 environment
conda create -n orbbec python=3.10

# Activate environment
conda activate orbbec

2.1.6.3. 3.3 Install Dependencies (Optional)

If your project requires other conda packages:

conda install numpy opencv

2.1.6.4. 3.4 Install pyorbbecsdk2

pip install --upgrade pyorbbecsdk2

Note: Even with conda, pyorbbecsdk2 must be installed via pip as it is not available in the conda repository.

2.1.6.5. 3.5 Exit Environment

conda deactivate

2.1.6.6. 3.6 Remove Environment (if needed)

conda remove -n orbbec --all

2.1.7. Platform-Specific Notes

2.1.7.1. Linux

2.1.7.1.1. Ubuntu/Debian

You may need to install python3-venv before using virtual environments:

sudo apt-get update
sudo apt-get install python3-venv

2.1.7.2. macOS

2.1.7.2.1. Xcode Command Line Tools

Ensure these are installed before creating virtual environments:

xcode-select --install

2.1.7.2.2. Permission Issues

Even with virtual environments, camera access still requires sudo:

# Correct
sudo -E python your_script.py

# Incorrect - may lack sufficient permissions
python your_script.py

2.1.7.3. Windows

2.1.7.3.1. Visual C++ Redistributable

Ensure Visual C++ Redistributable is installed (usually pre-installed).

2.1.7.3.2. PowerShell Execution Policy

If you encounter execution policy errors when activating the virtual environment:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

2.1.8. Troubleshooting

2.1.8.1. ❌ “externally-managed-environment” Error

Symptom:

error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install ...

Solution: Use a virtual environment!

python3 -m venv myenv
source myenv/bin/activate
pip install --upgrade pyorbbecsdk2

2.1.8.2. ❌ “No module named ‘venv’”

Symptom:

Error: No module named 'venv'

Solution: Install the venv module

Ubuntu/Debian:

sudo apt-get install python3-venv

CentOS/RHEL:

sudo yum install python3-devel

2.1.8.3. ❌ Virtual Environment Activated but Still Using System Python

Symptom: which python still shows /usr/bin/python

Solution: Check that the activate script executed successfully, or use the full path:

source ./orbbec_env/bin/activate
which python  # Should show .../orbbec_env/bin/python

2.1.8.4. ❌ pip install Shows Permission Denied

Symptom:

PermissionError: [Errno 13] Permission denied: '.../site-packages/...'

Solution: Ensure virtual environment is activated and do not use sudo:

# Incorrect - do not use sudo inside virtual environment
sudo pip install --upgrade pyorbbecsdk2

# Correct - install directly in virtual environment
pip install --upgrade pyorbbecsdk2

2.1.8.5. ❌ “pyorbbec_env/bin/activate: No such file”

Symptom: Activation command fails

Solution:

Check that you are in the correct directory
Check that virtual environment was created successfully: ls -la orbbec_env/bin/
Windows users should ensure correct path separators and script extensions

2.1.9. 📝 Best Practices

One environment per project: Create separate virtual environments for each pyorbbecsdk project
Don’t commit environment directory: Add virtual environment directories to .gitignore:
```
orbbec_env/
venv/
.venv/
__pycache__/
```
Document dependencies: Use pip freeze > requirements.txt to record dependencies
Document activation steps: Include environment activation instructions in your README

2.1. Virtual Environment Installation Guide

2.1.1. 📋 Table of Contents

2.1.2. 📊 Tool Selection Guide

2.1.3. Quick Start

2.1.3.1. Linux / macOS (venv)

2.1.3.2. Windows (venv)

2.1.4. 1. Using venv (Recommended for Beginners)

2.1.4.1. 1.1 Check Python Version

2.1.4.2. 1.2 Create Virtual Environment

2.1.4.3. 1.3 Activate Virtual Environment

2.1.4.4. 1.4 Install pyorbbecsdk2

2.1.4.5. 1.5 Verify Installation

2.1.4.6. 1.6 Run Examples

2.1.4.7. 1.7 Deactivate Virtual Environment

2.1.5. 2. Using pyenv (Multiple Python Versions)

2.1.5.1. 2.1 Install pyenv

2.1.5.2. 2.2 Install Python 3.10

2.1.5.3. 2.3 Set Local Python Version in Project Directory

2.1.5.4. 2.4 Create Virtual Environment and Activate

2.1.5.5. 2.5 Install pyorbbecsdk2

2.1.5.6. 2.6 Complete Workflow Example

2.1.6. 3. Using conda (Data Science Users)

2.1.6.1. 3.1 Install Miniconda

2.1.6.2. 3.2 Create conda Environment

2.1.6.3. 3.3 Install Dependencies (Optional)

2.1.6.4. 3.4 Install pyorbbecsdk2

2.1.6.5. 3.5 Exit Environment

2.1.6.6. 3.6 Remove Environment (if needed)

2.1.7. Platform-Specific Notes

2.1.7.1. Linux

2.1.7.1.1. Ubuntu/Debian

2.1.7.2. macOS

2.1.7.2.1. Xcode Command Line Tools

2.1.7.2.2. Permission Issues

2.1.7.3. Windows

2.1.7.3.1. Visual C++ Redistributable

2.1.7.3.2. PowerShell Execution Policy

2.1.8. Troubleshooting

2.1.8.1. ❌ “externally-managed-environment” Error

2.1.8.2. ❌ “No module named ‘venv’”

2.1.8.3. ❌ Virtual Environment Activated but Still Using System Python

2.1.8.4. ❌ pip install Shows Permission Denied

2.1.8.5. ❌ “pyorbbec_env/bin/activate: No such file”

2.1.9. 📝 Best Practices

2.1.10. 🔗 Related Documentation