/deepstream-dev

DeepStream Docker Containers Reference

Overview

DeepStream Docker images are hosted on the NVIDIA NGC container registry (nvcr.io). They package all SDK dependencies (GStreamer, TensorRT, CUDA, models, sample streams) and require the NVIDIA Container Toolkit (nvidia-container-toolkit) for GPU access.

• NGC catalog page: https://catalog.ngc.nvidia.com/orgs/nvidia/containers/deepstream
• Official docs: https://docs.nvidia.com/metropolis/deepstream/dev-guide/text/DS_docker_containers.html

Available Containers

dGPU (x86_64)

Jetson (ARM64/aarch64)

dGPU on ARM (GH200, GB200, SBSA)

Choosing the Right Image

NGC Authentication

Pulling images requires NGC authentication:

# 1. Get an API key from https://ngc.nvidia.com
# 2. Log in to the NGC registry
docker login nvcr.io
# Username: $oauthtoken
# Password: <YOUR_NGC_API_KEY>

Installing pyservicemaker Inside the Container

The pyservicemaker Python wheel is bundled in the container but NOT pre-installed. You must install it explicitly:

pip install /opt/nvidia/deepstream/deepstream/service-maker/python/pyservicemaker*.whl \
    pyyaml

In a Dockerfile:

RUN pip install --break-system-packages \
    /opt/nvidia/deepstream/deepstream/service-maker/python/pyservicemaker*.whl \
    pyyaml

Note: The --break-system-packages flag is needed on Ubuntu 24.04 (Python 3.12) to install into the system Python environment. Alternatively, use a virtual environment.

Installing pyservicemaker in a Python Virtual Environment

If pyservicemaker code runs from a venv, install the bundled wheel into that venv first:

python3 -m venv venv
source venv/bin/activate
pip install /opt/nvidia/deepstream/deepstream/service-maker/python/pyservicemaker*.whl \
    pyyaml
pip install -r requirements.txt

Running Containers

Prerequisites

1. Docker: Install docker-ce via official instructions
2. NVIDIA Container Toolkit: Install via install guide
3. NVIDIA Driver: 590+ for dGPU

Basic Run (with display)

export DISPLAY=:0
xhost +si:localuser:root

docker run -it --rm \
    --gpus all \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix/:/tmp/.X11-unix \
    nvcr.io/nvidia/deepstream:9.1-triton-multiarch

Headless Run (no display)

docker run -it --rm \
    --gpus all \
    nvcr.io/nvidia/deepstream:9.1-triton-multiarch

For headless mode, use fakesink instead of nveglglessink/nv3dsink in your pipeline, or output to a file with filesink.

Run with Custom Video File

docker run -it --rm \
    --gpus all \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix/:/tmp/.X11-unix \
    -v /path/to/videos:/data \
    nvcr.io/nvidia/deepstream:9.1-triton-multiarch

Building Custom Docker Images

Use a DeepStream image as the base for your application:

FROM nvcr.io/nvidia/deepstream:9.1-triton-multiarch

# Install pyservicemaker
RUN pip install --break-system-packages \
    /opt/nvidia/deepstream/deepstream/service-maker/python/pyservicemaker*.whl \
    pyyaml

# Copy application files
WORKDIR /app
COPY my_app.py .
COPY my_config.yml .

# Enable video driver libraries at runtime (encode/decode)
ENV NVIDIA_DRIVER_CAPABILITIES=${NVIDIA_DRIVER_CAPABILITIES},video

ENTRYPOINT ["python3", "my_app.py"]

Build and Run

# Build
docker build -t my-ds-app .

# Run with display
docker run --rm --gpus all \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    my-ds-app

# Run with RTSP source (no display needed)
docker run --rm --gpus all \
    my-ds-app rtsp://camera-ip/stream

Additional Packages

DeepStream containers do not include certain multimedia libraries by default. Install them if needed:

Audio/Codec Support

# Run the bundled install script for common multimedia packages
/opt/nvidia/deepstream/deepstream/user_additional_install.sh

# Or install specific packages manually
apt-get install -y gstreamer1.0-libav gstreamer1.0-plugins-good \
    gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly

ffmpeg (for sample video preparation scripts)

apt-get install --reinstall libflac8 libmp3lame0 libxvidcore4 ffmpeg

Kafka Support (librdkafka)

apt-get install -y librdkafka-dev

Tracker Support (libmosquitto)

apt-get install -y libmosquitto1

Important Paths Inside the Container

Environment Variables

Common Docker Issues

ModuleNotFoundError: No module named 'pyservicemaker'

Cause: The wheel is bundled but not installed.

Fix: Add to Dockerfile:

RUN pip install --break-system-packages \
    /opt/nvidia/deepstream/deepstream/service-maker/python/pyservicemaker*.whl \
    pyyaml

Display sinks fail with Could not open display

Cause: X11 forwarding not configured.

Fix: Pass display environment and socket:

docker run --rm --gpus all \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    my-ds-app

Or use fakesink / filesink for headless operation.

Pipeline exits early during non-interactive docker exec

Cause: Running without stdin can attach /dev/null; the GLib main loop may observe EOF and stop after the first frames.

Fix: Use docker exec -i for non-interactive pipeline scripts:

docker exec -i ds python3 /app/pipeline.py http://localhost:8080/sample.mp4

If the application must run without inherited stdin, install a pipe before importing pyservicemaker:

import os
_pipe_r, _pipe_w = os.pipe()
os.dup2(_pipe_r, 0)
os.close(_pipe_r)

Failed to load plugin ... libnvds_kafka_proto.so

Cause: librdkafka not installed (not bundled in the container).

Fix: Add to Dockerfile:

RUN apt-get update && apt-get install -y librdkafka-dev && rm -rf /var/lib/apt/lists/*

Warning about audio decoder not available

Cause: Multimedia codec packages removed in DeepStream containers.

Fix:

RUN /opt/nvidia/deepstream/deepstream/user_additional_install.sh