> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.stereolabs.com/docs/development/api-languages/python/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.stereolabs.com/_mcp/server.

# 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](https://www.stereolabs.com/developers/release/) (see the [installation guides](/docs/development/zed-sdk/))
* A CUDA-capable NVIDIA® GPU with [Compute Capability](https://developer.nvidia.com/cuda-gpus#compute) 7.5 or higher, as required by the [ZED SDK](/docs/development/zed-sdk/specifications/) 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](https://www.python.org/) (x64 version) and the [pip package manager](https://pip.pypa.io/en/stable/installation/). Then install the dependencies via pip in a terminal.

Linux:

```bash
python -m pip install cython numpy opencv-python pyopengl
```

Windows:

```powershell
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](/docs/development/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:
>
> ```bash
> 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:

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

> **Warning**
>
> 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:

```bash
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):

```bash
-> 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](/docs/tutorials/) and [Samples](/docs/samples).

> **Note**
>
> If you are using a virtual environment, make sure to activate it **before** running the script. Refer to [this page](/docs/development/api-languages/python/virtual-environment/) for more information.

## Troubleshooting

### "Numpy binary incompatibility"

```bash
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:

```bash
# 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
```

## Docs

- [Run a ZED Python Application](https://docs.stereolabs.com/docs/development/api-languages/python/run-a-python-application.md)
- [ZED Python API within a Virtual Environment](https://docs.stereolabs.com/docs/development/api-languages/python/virtual-environment.md)