DepthAI Python Library
Python bindings for C++ depthai-core library
Documentation
Documentation is available over at Luxonis DepthAI API
Installation
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 https://artifacts.luxonis.com/artifactory/luxonis-python-snapshot-local/ depthai
Building from source
Dependencies
- cmake >= 3.4
- C++14 compiler (clang, gcc, msvc, ...)
- Python3
Along these, dependencies of depthai-core are also required See: depthai-core dependencies
Building
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:
cd dephai-core/bindings/python
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
cd depthai-core/bindings/python
python3 -m pip wheel . -w wheelhouse --no-deps
Shared library
ℹ️ This is the recommended way when you are iterating as installing with pip is generally very slow for iteration.
To build a shared library from source perform the following:
cd depthai-core
cmake -H. -Bbuild -DDEPTHAI_BUILD_PYTHON=ON
cmake --build build
ℹ️ 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]
To specify custom Python executable to build for, use cmake -H. -Bbuild -D PYTHON_EXECUTABLE=/full/path/to/python.
⚠️ Important: To run python code directly with the shared library, you need to set the PYTHONPATH environment variable to the directory containing the shared library.
For example, on Linux:
export PYTHONPATH=$(pwd)/build/bindings/python
# Confirm that the right shared library is loaded
python3 -c "import depthai as dai; print(dai.__file__)"
# It should print the path to the shared library, something like /path/to/depthai-core/build/bindings/python/depthai.cpython-38-x86_64-linux-gnu.so
ℹ️ When using an IDE like VSCode, if you set the
PYTHONPATHbefore opening the IDE, it will correctly resolve autocompletion without needing to dopip install ..
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 -H. -Bbuild -D DEPTHAI_PYTHON_ENABLE_TESTS=ON -D DEPTHAI_PYTHON_ENABLE_EXAMPLES=ON -D DEPTHAI_PYTHON_TEST_EXAMPLES=ON
cmake --build build
Then navigate to build folder and run ctest
cd build
ctest
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
sudoif you have added your user to thedockergroup (or are using rootless docker). Then open http://localhost:8000.This docker container will watch changes in the
docs/sourcedirectory 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 -H. -Bbuild -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON cmake --build build --target sphinx python3 -m http.server --bind 0.0.0.0 8000 --directory build/docs/sphinxThen 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 sphinxThen refresh your page - it should load the updated website that was just built
Troubleshooting
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
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.
Linux/MacOS:
rm -r ~/.hunter
Windows:
del C:/.hunter
or
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: depthai.cpython-38-x86_64-linux-gnu.so] 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 http://ro.archive.ubuntu.com/ubuntu 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
1 maintainer
Metadata
1 maintainer
Release files for depthai 3.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-win_amd64.whl | CPython 3.10, CPython 3.11, CPython 3.12, CPython 3.14, CPython 3.9, CPython 3.13 | CPython 3.10, CPython 3.9, CPython 3.13, CPython 3.12, CPython 3.14, CPython 3.11 | Windows x86-64 | Details |
| depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-manylinux_2_28_x86_64.whl | CPython 3.9, CPython 3.11, CPython 3.12, CPython 3.13, CPython 3.14, CPython 3.10 | CPython 3.11, CPython 3.14, CPython 3.10, CPython 3.12, CPython 3.9, CPython 3.13 | Linux glibc 2.28+ x86-64 | Details |
| depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-manylinux_2_28_aarch64.whl | CPython 3.9, CPython 3.10, CPython 3.12, CPython 3.13, CPython 3.14, CPython 3.11 | CPython 3.11, CPython 3.14, CPython 3.10, CPython 3.12, CPython 3.13, CPython 3.9 | Linux glibc 2.28+ ARM64 | Details |
| depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-macosx_11_0_x86_64.whl | CPython 3.10, CPython 3.14, CPython 3.11, CPython 3.9, CPython 3.13, CPython 3.12 | CPython 3.12, CPython 3.13, CPython 3.14, CPython 3.9, CPython 3.10, CPython 3.11 | macOS 11.0+ x86-64 | Details |
| depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-macosx_11_0_arm64.whl | CPython 3.10, CPython 3.12, CPython 3.13, CPython 3.11, CPython 3.14, CPython 3.9 | CPython 3.14, CPython 3.10, CPython 3.11, CPython 3.12, CPython 3.9, CPython 3.13 | macOS 11.0+ ARM64 | Details |
Total release size: 384.4 MB
Release files / depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-win_amd64.whl
| Download URL | depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-win_amd64.whl |
|---|---|
| Size | 71.8 MB |
| Tags | CPython 3.10 CPython 3.11 CPython 3.12 CPython 3.13 CPython 3.14 CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
49259f1a8486a3eeb5cdef95030b95b485c31690874af19d345eeab2c4800a77
|
|
BLAKE2b-256 checksum How to use checksums |
92d68bb7d4f523ca0d40aa4f8e19942f7a2cd554628cd6127d978dd1ce9c62fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-manylinux_2_28_x86_64.whl
| Download URL | depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 89.3 MB |
| Tags | CPython 3.10 CPython 3.11 CPython 3.12 CPython 3.13 CPython 3.14 CPython 3.9 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
f035fb1b150b3b440601d63b778ca879e98186b5cc6d697475bca4e0d7aee615
|
|
BLAKE2b-256 checksum How to use checksums |
9cc754298f010d2648831fdbca59dbc72a7e83722bed3e05fdf361f4a4b3eb6b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-manylinux_2_28_aarch64.whl
| Download URL | depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 83.6 MB |
| Tags | CPython 3.10 CPython 3.11 CPython 3.12 CPython 3.13 CPython 3.14 CPython 3.9 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
c828e08ff0de64c666a33ae3cfa09c6a45155d704e14e83369ec6e9b6d7f431f
|
|
BLAKE2b-256 checksum How to use checksums |
5e9d9c483bd6db6b35b83727a954932c8080ada78c7ca0ce63d9b773a7b60e2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-macosx_11_0_x86_64.whl
| Download URL | depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-macosx_11_0_x86_64.whl |
|---|---|
| Size | 71.7 MB |
| Tags | CPython 3.10 CPython 3.11 CPython 3.12 CPython 3.13 CPython 3.14 CPython 3.9 macOS 11.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
47e7b84123ac8822925179cfa5534aafb19ce648c0a844c554fe373d043ff7f9
|
|
BLAKE2b-256 checksum How to use checksums |
b47f9bf7295af0a08dee1de560423d09964df6320a2a661b619beb22b24ef739
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-macosx_11_0_arm64.whl
| Download URL | depthai-3.11.0-cp39.cp310.cp311.cp312.cp313.cp314-cp39.cp310.cp311.cp312.cp313.cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 68.0 MB |
| Tags | CPython 3.10 CPython 3.11 CPython 3.12 CPython 3.13 CPython 3.14 CPython 3.9 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d152c8b37d35951e9cdb8ded236414748004e1fecb97f0447a8c2ff28627c423
|
|
BLAKE2b-256 checksum How to use checksums |
672fab1f8254598da8f5601543cfac165e422e9322e5607ddd27e023fb326b39
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
