# DepthAI Python Library
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/depthai/)
[](https://github.com/luxonis/depthai-python/actions/workflows/main.yml)
Python bindings for C++ depthai-core library
## Documentation
Documentation is available over at [Luxonis DepthAI API](https://docs.luxonis.com/projects/api/en/latest/)
## Installation
Prebuilt wheels are available in [Luxonis repository](https://artifacts.luxonis.com/artifactory/luxonis-python-snapshot-local/)
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](https://github.com/luxonis/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
```
#### 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 `PYTHONPATH` before opening the IDE, it will correctly resolve autocompletion without needing to do `pip 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](https://docs.docker.com/) (with [Docker Compose](https://docs.docker.com/compose/install/))**
```
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](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](#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/sphinx
```
Then open [http://localhost:8000](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
## Troubleshooting
### Relocation link error
Build failure on Ubuntu 18.04 ("relocation ..." link error) with gcc 7.4.0 (default) - [**issue #3**](https://github.com/luxonis/depthai-api/issues/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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/luxonis/depthai-core/tree/main/bindings/python",
"name": "depthai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Luxonis",
"author_email": "support@luxonis.com",
"download_url": null,
"platform": null,
"description": "# DepthAI Python Library\n\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/depthai/)\n[](https://github.com/luxonis/depthai-python/actions/workflows/main.yml)\n\nPython bindings for C++ depthai-core library\n\n## Documentation\n\nDocumentation is available over at [Luxonis DepthAI API](https://docs.luxonis.com/projects/api/en/latest/)\n\n## Installation\n\nPrebuilt wheels are available in [Luxonis repository](https://artifacts.luxonis.com/artifactory/luxonis-python-snapshot-local/)\nMake sure pip is upgraded\n```\npython3 -m pip install -U pip\npython3 -m pip install --extra-index-url https://artifacts.luxonis.com/artifactory/luxonis-python-snapshot-local/ depthai\n```\n## Building from source\n\n### Dependencies\n - cmake >= 3.4\n - C++14 compiler (clang, gcc, msvc, ...)\n - Python3\n\nAlong these, dependencies of depthai-core are also required\nSee: [depthai-core dependencies](https://github.com/luxonis/depthai-core#dependencies)\n\n\n### Building\n\nThe first time you build, the repository submodules need be initialized:\n```\ngit submodule update --init --recursive\n\n# Tip: You can ask Git to do that automatically:\ngit config submodule.recurse true\n```\n\nLater submodules also need to be updated.\n\n#### Local build with pip\nTo build and install using pip:\n```\ncd dephai-core/bindings/python\npython3 -m pip install .\n```\nAdd parameter `-v` to see the output of the building process.\n\n#### Wheel with pip\nTo build a wheel, execute the following\n```\ncd depthai-core/bindings/python\npython3 -m pip wheel . -w wheelhouse\n```\n\n#### Shared library\n> \u2139\ufe0f This is the recommended way when you are iterating as installing with pip is generally very slow for iteration.\n\nTo build a shared library from source perform the following:\n```\ncd depthai-core\ncmake -H. -Bbuild -DDEPTHAI_BUILD_PYTHON=ON\ncmake --build build\n```\n> \u2139\ufe0f To speed up build times, use `cmake --build build --parallel [num CPU cores]` (CMake >= 3.12).\n> For older versions use: Linux/macOS: `cmake --build build -- -j[num CPU cores]`, MSVC: `cmake --build build -- /MP[num CPU cores]`\n\nTo specify custom Python executable to build for, use `cmake -H. -Bbuild -D PYTHON_EXECUTABLE=/full/path/to/python`.\n\n\u26a0\ufe0f **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.\nFor example, on Linux:\n```\nexport PYTHONPATH=$(pwd)/build/bindings/python\n# Confirm that the right shared library is loaded\npython3 -c \"import depthai as dai; print(dai.__file__)\"\n# 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\n```\n> \u2139\ufe0f When using an IDE like VSCode, if you set the `PYTHONPATH` before opening the IDE, it will correctly resolve autocompletion without needing to do `pip install .`.\n\n#### Common issues\n\n* Many build fails due to missing dependencies. This also happens when submodules are missing or outdated (`git submodule update --recursive`).\n* 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 .`\n* 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.\n\n\n## Running tests\n\nTo run the tests build the library with the following options\n```\ngit submodule update --init --recursive\ncmake -H. -Bbuild -D DEPTHAI_PYTHON_ENABLE_TESTS=ON -D DEPTHAI_PYTHON_ENABLE_EXAMPLES=ON -D DEPTHAI_PYTHON_TEST_EXAMPLES=ON\ncmake --build build\n```\n\nThen navigate to `build` folder and run `ctest`\n```\ncd build\nctest\n```\n\nTo test a specific example/test with a custom timeout (in seconds) use following:\n```\nTEST_TIMEOUT=0 ctest -R \"01_rgb_preview\" --verbose\n```\nIf `TEST_TIMEOUT=0`, the test will run until stopped or it ends.\n\n## Tested platforms\n\n- Windows 10, Windows 11\n- Ubuntu 18.04, 20.04, 22.04;\n- Raspbian 10;\n- macOS 10.14.6, 10.15.4;\n\n### Building documentation\n\n- **Using [Docker](https://docs.docker.com/) (with [Docker Compose](https://docs.docker.com/compose/install/))**\n\n ```\n cd docs\n sudo docker-compose build\n sudo docker-compose up\n ```\n\n > \u2139\ufe0f You can leave out the `sudo` if you have added your user to the `docker` group (or are using rootless docker).\n Then open [http://localhost:8000](http://localhost:8000).\n\n This docker container will watch changes in the `docs/source` directory and rebuild the docs automatically\n\n- **Linux**\n\n First, please install the required [dependencies](#Dependencies)\n\n Then run the following commands to build the docs website\n\n ```\n python3 -m pip install -U pip\n python3 -m pip install -r docs/requirements.txt\n cmake -H. -Bbuild -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON\n cmake --build build --target sphinx\n python3 -m http.server --bind 0.0.0.0 8000 --directory build/docs/sphinx\n ```\n\n Then open [http://localhost:8000](http://localhost:8000).\n\n This will build documentation based on current sources, so if some new changes will be made, run this command\n in a new terminal window to update the website source\n\n ```\n cmake --build build --target sphinx\n ```\n\n Then refresh your page - it should load the updated website that was just built\n\n## Troubleshooting\n\n### Relocation link error\n\nBuild failure on Ubuntu 18.04 (\"relocation ...\" link error) with gcc 7.4.0 (default) - [**issue #3**](https://github.com/luxonis/depthai-api/issues/3)\n - the solution was to upgrade gcc to version 8:\n\n sudo apt install g++-8\n sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-8 70\n sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-8 70\n### Hunter\nHunter is a CMake-only dependency manager for C/C++ projects.\n\nIf you are stuck with error message which mentions external libraries (subdirectory of `.hunter`) like the following:\n```\n/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'\n```\n\nTry erasing the **Hunter** **cache** folder.\n\nLinux/MacOS:\n```\nrm -r ~/.hunter\n```\nWindows:\n```\ndel C:/.hunter\n```\nor\n```\ndel C:/[user]/.hunter\n```\n\n### LTO - link time optimization\n\nIf following message appears:\n```\nlto1: internal compiler error: in add_symbol_to_partition_1, at lto/lto-partition.c:152\nPlease submit a full bug report,\nwith preprocessed source if appropriate.\nSee <file:///usr/share/doc/gcc-10/README.Bugs> for instructions.\nlto-wrapper: fatal error: /usr/bin/c++ returned 1 exit status\ncompilation terminated.\n/usr/bin/ld: error: lto-wrapper failed\ncollect2: error: ld returned 1 exit status\nmake[2]: *** [CMakeFiles/depthai.dir/build.make:227: depthai.cpython-38-x86_64-linux-gnu.so] Error 1\nmake[1]: *** [CMakeFiles/Makefile2:98: CMakeFiles/depthai.dir/all] Error 2\nmake: *** [Makefile:130: all] Error 2\n```\n\nOne fix is to update linker: (In case you are on Ubuntu 20.04: `/usr/bin/ld --version`: 2.30)\n```\n# Add to the end of /etc/apt/sources.list:\n\necho \"deb http://ro.archive.ubuntu.com/ubuntu groovy main\" >> /etc/apt/sources.list\n\n# Replace ro with your countries local cache server (check the content of the file to find out which is)\n# Not mandatory, but faster\n\nsudo apt update\nsudo apt install binutils\n\n# Should upgrade to 2.35.1\n# Check version:\n/usr/bin/ld --version\n# Output should be: GNU ld (GNU Binutils for Ubuntu) 2.35.1\n# Revert /etc/apt/sources.list to previous state (comment out line) to prevent updating other packages.\nsudo apt update\n```\n\nAnother option is to use **clang** compiler:\n```\nsudo apt install clang-10\nmkdir build && cd build\nCC=clang-10 CXX=clang++-10 cmake ..\ncmake --build . --parallel\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "DepthAI Python Library",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/luxonis/depthai-core/tree/main/bindings/python"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1960a88593ed92c8112a8403daae137d57f35a8c8b4917f7d01dff4d8116def9",
"md5": "efc04603fe03ffb5acc96eebb71477b6",
"sha256": "8de200a81d779a211970c0b2804e0da0ae00acad9db1ca78dbf4577f86a89f41"
},
"downloads": -1,
"filename": "depthai-3.0.0-cp310-cp310-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "efc04603fe03ffb5acc96eebb71477b6",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.7",
"size": 100475214,
"upload_time": "2025-09-07T21:39:24",
"upload_time_iso_8601": "2025-09-07T21:39:24.588468Z",
"url": "https://files.pythonhosted.org/packages/19/60/a88593ed92c8112a8403daae137d57f35a8c8b4917f7d01dff4d8116def9/depthai-3.0.0-cp310-cp310-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "652edfcb8e5a89fe641f307532e2213c3ca500cc11cd8755ff3dc4cb8ba13a8a",
"md5": "e405fb2e6d96a1b0fe5c5542bc0d0d1f",
"sha256": "3c73c5cd09199f3083e1141a7a42fb78f92eff12056b075dba55e6ae8879a262"
},
"downloads": -1,
"filename": "depthai-3.0.0-cp310-cp310-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "e405fb2e6d96a1b0fe5c5542bc0d0d1f",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.7",
"size": 92672583,
"upload_time": "2025-09-07T21:39:31",
"upload_time_iso_8601": "2025-09-07T21:39:31.970207Z",
"url": "https://files.pythonhosted.org/packages/65/2e/dfcb8e5a89fe641f307532e2213c3ca500cc11cd8755ff3dc4cb8ba13a8a/depthai-3.0.0-cp310-cp310-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "048be9946e448092b0183954c34a8e8650e9e003df011d0e9597f2d6b350e588",
"md5": "3e69c3d3a8f28831987a1eac92415c0f",
"sha256": "7a4256a07eb347294379ab42ad71d558e94d27fe1ae7435bbe4e6dc2a6651283"
},
"downloads": -1,
"filename": "depthai-3.0.0-cp310-cp310-win_amd64.whl",
"has_sig": false,
"md5_digest": "3e69c3d3a8f28831987a1eac92415c0f",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.7",
"size": 72958520,
"upload_time": "2025-09-07T21:39:48",
"upload_time_iso_8601": "2025-09-07T21:39:48.650266Z",
"url": "https://files.pythonhosted.org/packages/04/8b/e9946e448092b0183954c34a8e8650e9e003df011d0e9597f2d6b350e588/depthai-3.0.0-cp310-cp310-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 21:39:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "luxonis",
"github_project": "depthai-core",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "depthai"
}
JSON
