Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
January 26, 2023 18:02
November 24, 2023 11:41
November 17, 2023 16:41
September 30, 2023 23:58
December 12, 2022 21:34
June 14, 2020 00:12
January 20, 2022 12:26
March 12, 2020 01:13
October 9, 2020 11:40

DepthAI Python Library

License: MIT Python Wheel CI

Python bindings for C++ depthai-core library


Documentation is available over at Luxonis DepthAI API


Prebuilt wheels are available in Luxonis repository Make sure pip is upgraded

python3 -m pip install -U pip
python3 -m pip install --extra-index-url depthai

Building from source


  • cmake >= 3.4
  • C++14 compiler (clang, gcc, msvc, ...)
  • Python3

Along these, dependencies of depthai-core are also required See: depthai-core dependencies


The first time you build, the repository submodules need be initialized:

git submodule update --init --recursive

# Tip: You can ask Git to do that automatically:
git config submodule.recurse true

Later submodules also need to be updated.

Local build with pip

To build and install using pip:

python3 -m pip install .

Add parameter -v to see the output of the building process.

Wheel with pip

To build a wheel, execute the following

python3 -m pip wheel . -w wheelhouse

Shared library

To build a shared library from source perform the following:

ℹ️ To speed up build times, use cmake --build build --parallel [num CPU cores] (CMake >= 3.12). For older versions use: Linux/macOS: cmake --build build -- -j[num CPU cores], MSVC: cmake --build build -- /MP[num CPU cores]

cmake -H. -Bbuild
cmake --build build

To specify custom Python executable to build for, use cmake -H. -Bbuild -D PYTHON_EXECUTABLE=/full/path/to/python.

Common issues

  • Many build fails due to missing dependencies. This also happens when submodules are missing or outdated (git submodule update --recursive).
  • If libraries and headers are not in standard places, or not on the search paths, CMake reports it cannot find what it needs (e.g. libusb). CMake can be hinted at where to look, for exmpale: CMAKE_LIBRARY_PATH=/opt/local/lib CMAKE_INCLUDE_PATH=/opt/local/include pip install .
  • Some distribution installers may not get the desired library. For example, an install on a RaspberryPi failed, missing libusb, as the default installation with APT led to v0.1.3 at the time, whereas the library here required v1.0.

Running tests

To run the tests build the library with the following options

git submodule update --init --recursive
cmake --build build

Then navigate to build folder and run ctest

cd build

To test a specific example/test with a custom timeout (in seconds) use following:

TEST_TIMEOUT=0 ctest -R "01_rgb_preview" --verbose

If TEST_TIMEOUT=0, the test will run until stopped or it ends.

Tested platforms

  • Windows 10, Windows 11
  • Ubuntu 18.04, 20.04, 22.04;
  • Raspbian 10;
  • macOS 10.14.6, 10.15.4;

Building documentation

  • Using Docker (with Docker Compose)

    cd docs
    sudo docker-compose build
    sudo docker-compose up

    ℹ️ You can leave out the sudo if you have added your user to the docker group (or are using rootless docker). Then open http://localhost:8000.

    This docker container will watch changes in the docs/source directory and rebuild the docs automatically

  • Linux

    First, please install the required dependencies

    Then run the following commands to build the docs website

    python3 -m pip install -U pip
    python3 -m pip install -r docs/requirements.txt
    cmake --build build --target sphinx
    python3 -m http.server --bind 8000 --directory build/docs/sphinx

    Then open http://localhost:8000.

    This will build documentation based on current sources, so if some new changes will be made, run this command in a new terminal window to update the website source

    cmake --build build --target sphinx

    Then refresh your page - it should load the updated website that was just built


Relocation link error

Build failure on Ubuntu 18.04 ("relocation ..." link error) with gcc 7.4.0 (default) - issue #3

  • the solution was to upgrade gcc to version 8:

    sudo apt install g++-8
    sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-8 70
    sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-8 70


Hunter is a CMake-only dependency manager for C/C++ projects.

If you are stuck with error message which mentions external libraries (subdirectory of .hunter) like the following:

/usr/bin/ld: /home/[user]/.hunter/_Base/062a19a/ccfed35/a84a713/Install/lib/liblzma.a(stream_flags_decoder.c.o): warning: relocation against `lzma_footer_magic' in read-only section `.text'

Try erasing the Hunter cache folder.


rm -r ~/.hunter


del C:/.hunter


del C:/[user]/.hunter

LTO - link time optimization

If following message appears:

lto1: internal compiler error: in add_symbol_to_partition_1, at lto/lto-partition.c:152
Please submit a full bug report,
with preprocessed source if appropriate.
See <file:///usr/share/doc/gcc-10/README.Bugs> for instructions.
lto-wrapper: fatal error: /usr/bin/c++ returned 1 exit status
compilation terminated.
/usr/bin/ld: error: lto-wrapper failed
collect2: error: ld returned 1 exit status
make[2]: *** [CMakeFiles/depthai.dir/build.make:227:] Error 1
make[1]: *** [CMakeFiles/Makefile2:98: CMakeFiles/depthai.dir/all] Error 2
make: *** [Makefile:130: all] Error 2

One fix is to update linker: (In case you are on Ubuntu 20.04: /usr/bin/ld --version: 2.30)

# Add to the end of /etc/apt/sources.list:

echo "deb groovy main" >> /etc/apt/sources.list

# Replace ro with your countries local cache server (check the content of the file to find out which is)
# Not mandatory, but faster

sudo apt update
sudo apt install binutils

# Should upgrade to 2.35.1
# Check version:
/usr/bin/ld --version
# Output should be: GNU ld (GNU Binutils for Ubuntu) 2.35.1
# Revert /etc/apt/sources.list to previous state (comment out line) to prevent updating other packages.
sudo apt update

Another option is to use clang compiler:

sudo apt install clang-10
mkdir build && cd build
CC=clang-10 CXX=clang++-10 cmake ..
cmake --build . --parallel