DeepStream Python Apps: pybind11 bindings and eighteen sample pipelines

A deprecation notice in the first screen of the README

The second bold paragraph of this README is the most important text in the repository. It states that since the DeepStream Python bindings are deprecated, there will be no more wheel files released from DeepStream 9.0 onwards, that users should build wheels using the instructions in the bindings README, and that users are recommended to use PyServiceMaker instead.

That reframes everything else. The line above it declares SDK version supported: 9.0, and notes that this release supports Ubuntu 24.04 with Python 3.12 and gst-python 1.24.1. So the repository describes itself as current for SDK 9.0 while announcing that the artefact you would normally install for SDK 9.0 will not exist.

The last push to this repository was on 2026-04-01, and the newest tagged release is v1.2.2 from 2025-09-15, whose notes say it is compatible with DeepStream SDK 8.0 on Ubuntu 24.04 with Python 3.12. Those two facts do not contradict each other exactly, but they do mean the tagged history stops one SDK version behind the version the README targets. Anything newer than SDK 8.0 is source-only.

The default branch is `master` rather than `main`, and GitHub reports Jupyter Notebook as the primary language, which reflects the `notebooks/` directory rather than the bulk of the code. GitHub also reports no recognised license, though a `LICENSE` and a separate `THIRD_PARTY_LICENSE` sit at the root.

Building pybind11 bindings when no wheel exists

The bindings expose the DeepStream C metadata structures and functions to Python, and the module is generated with Pybind11. Without a published wheel for your SDK version, the source under `bindings/` plus its README is the installation path.

Two environments are required, and the README is explicit about both. Python 3.12 needs a virtual environment to install and import pip packages:

sudo apt install python3-venv

# Create a venv for pyds
python3 -m venv pyds
(for Spark - bug fix)
python3 -m venv --system-site-packages pyds
# Activate the environment
source ./pyds/bin/activate

The `--system-site-packages` variant is annotated for a Spark bug fix, which tells you the author hit a case where the isolated environment could not see something it needed.

There is also a NumPy constraint, and unlike most version warnings this one bites:

pip3 install --force-reinstall numpy==1.26.0

NumPy 2.x is not supported, and the instruction is to downgrade. That note has appeared in the release notes across several versions, most recently in v1.2.2 and v1.2.0, so it is a persistent constraint rather than a transient issue.

Build mechanics have also moved. The README notes that PyDS 1.2.0 and later for DeepStream 7.1 and above uses an updated PyPA build system to support pip 24.2 and later, which deprecated the `setup.py` command line, and v1.2.2 records the same change again. In other words, the old build path is genuinely gone and the instructions in `bindings/` reflect that.

Two guides are offered for contributors: one on contributing to the bindings, and one for advanced cases such as writing bindings for your own data structures.

Eighteen sample applications, each isolating one capability

The samples are the reason to read this repository, and they are arranged so each one demonstrates a single thing. `deepstream-test1` is a four-class object detection pipeline and also shows the newer nvstreammux. `deepstream-test2` adds tracking and attribute classification. `deepstream-test3` is the multi-stream workhorse, adding Triton inference server support, no-display mode, file loop and silent mode, which is the one you will adapt for anything real.

The rest isolate capability rather than size. `deepstream-imagedata-multistream` reaches the image buffers directly. `deepstream-opticalflow` returns flow vectors in a NumPy array. `deepstream-segmentation` does the same for segmentation masks. `deepstream-imagedata-multistream-cupy` pulls the GPU buffer as a CuPy array, x86 only. `deepstream-segmask` shows how to read NvOSD_MaskParams. `deepstream-nvdsanalytics` wires in the analytics plugin.

Then there are the pipeline-shape samples: `runtime_source_add_delete` adds and removes sources at runtime, `deepstream-demux-multi-in-multi-out` splits buffers with nvstreamdemux, `deepstream-preprocess-test` configures custom ROIs with nvdspreprocess, and `deepstream-rtsp-in-rtsp-out` round-trips RTSP with a command line option for attaching the timestamp to the source rather than the streammux.

Two samples are about redaction and privacy. `deepstream-imagedata-multistream-redaction` does face detection and redaction, with a note that it now uses a local sink instead of RTSP output. `deepstream-custom-binding-test` demonstrates attaching a custom data structure through NvDsUserMeta.

Three variants round out the list for hardware and edge cases: `deepstream-test1-usbcam` for USB camera input, `deepstream-test1-rtsp-out` for adding a software encoder to support Jetson Orin Nano, and `deepstream-test4` for sending analytics to the cloud through a message broker.

Each subdirectory under `apps/` carries its own detail, which is where you should go once you have picked the closest one. The practical pattern is to copy the nearest sample and modify it, rather than build a pipeline from nothing.

Where documentation lives, and one breaking change to know about

The repository is documentation-heavy in a good way. `HOWTO.md` is the guide for using the bindings and for writing your own apps, and it is the document the README points to twice, once for metadata access and once for the samples. `FAQ.md` and `bindings/README.md` cover the build, and `docs/` and `notebooks/` hold the rest.

One API break is documented prominently and will affect you if you upgrade. The binding for `alloc_nvds_event_msg_meta()` now expects an NvDsUserMeta pointer that the NvDsEventMsgMeta is associated with, rather than the previous signature. The README points at `deepstream-test4` and `bindings/src/bindschema.cpp` as references, which is the pattern worth following for any binding change: the sample and the binding source are updated together.

The samples have also shed members over time. The deepstream-ssd-parser app has been removed because SSD models are deprecated, and v1.2.2 removed it again from the release. v1.2.0 recorded that segmentation apps were not supported in DeepStream 7.1, though `deepstream-segmentation` and `deepstream-segmask` are present in the current application list, so that constraint appears lifted.

The v1.1.11 notes are still worth reading for one detail that shows the platform-awareness of the code. A `platform_info()` module was added for checking WSL, integrated GPU and aarch64, and all apps and integration tests were updated to use it rather than testing platform themselves, with `deepstream_test1` given as the simple usage example. SBSA support came in the same release. That is the difference between sample code you can port to a different machine and sample code you cannot.

Editorial conclusion

This repository is a good answer to a narrow question and a bad answer to a durable one. If you need to read DeepStream metadata from Python today, the sample applications are the fastest route, because each one is a working pipeline with the binding call already in place. The problem is what the README now says outright: the bindings are deprecated, PyServiceMaker is the recommended path, and no wheel files will be published from DeepStream 9.0 onwards, so anyone starting new has to build from source under `bindings/`. The samples themselves are versioned tightly against the SDK, with eighteen of them pinned to specific plugin behaviours and at least one, the SSD parser app, already removed because its models are deprecated. Read `HOWTO.md` and `bindings/README.md` first, copy the nearest sample rather than assembling a pipeline from scratch, and confirm your SDK version against the README's stated 9.0 before assuming any of it applies.

Frequently asked questions

Official sources

1. Issues
2. NVIDIA-AI-IOT/deepstream_python_apps on GitHub
3. README
4. Releases