Install the ZED Python API

This section explains how to use the ZED SDK in Python 3 on Windows and Linux platforms.

Getting Started

The Python API is a wrapper around the ZED SDK which is written in C++ optimized code. We make the ZED SDK accessible from external Python code using Cython.

To start using the ZED SDK in Python, you will need to install the following dependencies on your system:

ZED SDK (see the installation guides)
A CUDA-capable NVIDIA® GPU with Compute Capability 7.5 or higher, as required by the ZED SDK itself. The Python API is a wrapper around the SDK and cannot be installed or used without CUDA and a compatible GPU.
Python 3.8 to 3.14 (x64)
Cython 3.0+
NumPy 2.x (NumPy 1.x on Python 3.8)
OpenCV Python (optional)
PyOpenGL (optional)

Make sure to install Python (x64 version) and the pip package manager. Then install the dependencies via pip in a terminal.

Linux:

python -m pip install cython numpy opencv-python pyopengl

Windows:

py -m pip install cython numpy opencv-python pyopengl

Installing the Python API

Install the ZED SDK first

The Python API (pyzed) is not a standalone package: the ZED SDK must be installed on your machine first. The get_python_api.py install script is part of the SDK and lives in its installation folder (/usr/local/zed/ on Linux, C:\Program Files (x86)\ZED SDK\ on Windows).

The script automatically detects your platform, CUDA and Python version, and downloads the corresponding pre-compiled Python API package.

On Linux, the SDK installer offers to run this script for you at the end of the installation. Press Y when prompted:

Do you want to install the Python API (recommended) [Y/n] ?

If you answered n at that step, or want to install the API in another Python environment, run the script manually at any time as described below.

Running the install script

Windows

The Python install script is located in C:\Program Files (x86)\ZED SDK\.

Open an Administrator PowerShell and run the script:

cd "C:\Program Files (x86)\ZED SDK\"
py get_python_api.py

Admin access is required to run the script in the Program Files folder. If you see a Permission denied error, right-click PowerShell and choose Run as administrator, or copy get_python_api.py to another folder (e.g. your Desktop) and run it from there.

Linux

The Python install script is located in /usr/local/zed/.

Run the script:

cd "/usr/local/zed/"
python3 get_python_api.py

Example output (from an older ZED SDK 4.2 installation; the versions shown depend on your ZED SDK, Python and CUDA versions):

-> Downloading to '/usr/local/zed'
Detected platform: 
    linux_x86_64
    Python 3.10
    ZED SDK 4.2
-> Checking if https://download.stereolabs.com/zedsdk/4.2/whl/linux_x86_64/pyzed-4.2-cp310-cp310-linux_x86_64.whl exists and is available
-> Found ! Downloading python package into /usr/local/zed/pyzed-4.2-cp310-cp310-linux_x86_64.whl
-> Installing necessary dependencies
Defaulting to user installation because normal site-packages is not writeable
Requirement already satisfied: numpy in /home/<user>/.local/lib/python3.10/site-packages (1.23.4)
Defaulting to user installation because normal site-packages is not writeable
Processing ./pyzed-4.2-cp310-cp310-linux_x86_64.whl
Collecting numpy<2.0,>=1.13 (from pyzed==4.2)
  Using cached numpy-1.26.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (61 kB)
Collecting cython>=3.0.0 (from pyzed==4.2)
  Using cached Cython-3.0.11-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (3.2 kB)
Using cached Cython-3.0.11-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.6 MB)
Using cached numpy-1.26.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (18.2 MB)
Installing collected packages: numpy, cython, pyzed
Successfully installed cython-3.0.11 numpy-1.26.4 pyzed-4.2
Done
  To install it later or on a different environment run : 
 python -m pip install --ignore-installed /usr/local/zed/pyzed-4.2-cp310-cp310-linux_x86_64.whl

That’s it! The Python API is now installed. To get started, check out our Tutorials and Samples.

If you are using a virtual environment, make sure to activate it before running the script. Refer to this page for more information.

Troubleshooting

”Numpy binary incompatibility”

Traceback (most recent call last):
    ...
    File "__init__.pxd", line 918, in init pyzed.sl
ValueError: numpy.ufunc size changed, may indicate binary incompatibility. Expected 216 from C header, got 192 from PyObject

This error usually means the installed NumPy version does not match the one pyzed was built against (an ABI/version mismatch). Reinstalling or upgrading NumPy (and reinstalling pyzed with the install script) resolves it. Run these commands:

# On NVIDIA® Jetson™ (aarch64) cython needs to be installed first since numpy needs to be compiled.
python3 -m pip install cython
python3 -m pip install numpy