Manage ZED SDK Containers and Images

This page explains how to choose a ZED SDK Docker image, how to list, stop, remove, and clean up containers and images, and how to keep the AI models and calibration files when a container is recreated. It applies to both desktop and NVIDIA® Jetson™ hosts.

Two terms are used throughout the page:

An image is a read-only template, such as stereolabs/zed:5.5-runtime-cuda13.0-ubuntu22.04. Images are downloaded with docker pull or built with docker build.
A container is a running (or stopped) instance of an image. Every docker run command creates a new container with its own writable filesystem, which is deleted when the container is removed.

Choose a ZED SDK Image

The ZED SDK images are published in several variants. The variant is the part of the tag that follows the ZED SDK version: runtime in stereolabs/zed:5.5-runtime-cuda13.0-ubuntu22.04, or tools-devel in stereolabs/zed:5.5-tools-devel-l4t-r36.5.

Variant	Available for	Content	Use it to
`runtime`	Desktop, Jetson™	The ZED SDK runtime libraries and their dependencies. No headers, no tools, no samples.	Run an already compiled application. This is the image to deploy in production.
`devel`	Desktop, Jetson™	The `runtime` content, plus the ZED SDK headers and the build tools (compiler, CMake, CUDA development files). No tools, no samples.	Compile your own application, interactively or as the build stage of your Dockerfile.
`gl-devel`	Desktop	The `devel` content, plus OpenGL support and the ZED tools and samples.	Run the graphical ZED tools (ZED Explorer, ZED Depth Viewer, ZED Diagnostic) and the samples on a desktop host.
`tools-devel`	Jetson™	The complete ZED SDK installation: headers, ZED tools, and samples.	Run the ZED tools and the samples on a Jetson™. This is the most complete Jetson™ image.
`py-runtime`	Jetson™	The `runtime` content, plus the ZED Python API.	Run a Python application on a Jetson™.
`py-devel`	Jetson™	The `devel` content, plus the ZED Python API.	Develop a Python application on a Jetson™.

A few points to keep in mind when choosing:

For production, use runtime. On desktop, a runtime image is about three times smaller than the matching devel image (about 2 GB compressed instead of 6 GB), because it does not include the CUDA development toolchain.
To build, use devel, then ship runtime. With a multi-stage build, compile your application in a devel stage and copy the binaries into a runtime stage.
To run a ZED tool or a sample, use tools-devel (Jetson™) or gl-devel (desktop). The runtime and devel images do not include them. At the time of writing, the gl-devel variant is not yet published for ZED SDK 5.5, see Install on Linux.
Python on desktop needs no specific variant. All desktop images include the ZED Python API. The py-runtime and py-devel variants exist only for Jetson™.
OpenGL on Jetson™ needs no specific variant. All Jetson™ images support display output. On desktop, only gl-devel images can open a window.

The ZED SDK version of a tag can be written as 5.5 or 5.5.0. A 5.5 tag follows the latest patch release of ZED SDK 5.5, while a 5.5.0 tag always points to that exact release. Use the full version to make sure every machine of a fleet runs the same ZED SDK.

See Install on Linux and Install on NVIDIA® Jetson™ for the full tag format and the available CUDA, Ubuntu, and L4T combinations.

Manage Containers

Start a Container with a Name

By default, Docker gives each new container a random name. Use --name to choose one, so the container is easy to find and to control later:

docker run --gpus all -it --privileged --name zed stereolabs/zed:<container_tag>

A container name is unique: running the same command a second time fails with a Conflict. The container name "/zed" is already in use error until the first container is removed. To create a temporary container that is deleted automatically as soon as it exits, add the --rm option.

List Containers

docker ps        # running containers
docker ps -a     # all containers, including the stopped ones

Example output of docker ps -a, with one running container and one stopped container:

CONTAINER ID   IMAGE                                             COMMAND                  CREATED          STATUS                      PORTS     NAMES
3f2a9c1d7b4e   stereolabs/zed:5.5-runtime-cuda13.0-ubuntu22.04   "/opt/nvidia/nvidia_e…"   12 minutes ago   Up 12 minutes                         zed
8c41e0b9a6d2   stereolabs/zed:5.5-runtime-cuda13.0-ubuntu22.04   "/opt/nvidia/nvidia_e…"   2 days ago       Exited (0) 26 hours ago               zed-test

The STATUS column shows whether a container is running (Up) or stopped (Exited), and the NAMES column gives the name to use in the commands below. A stopped container no longer uses the GPU or the camera, but it still uses disk space.

Stop, Restart, and Reopen a Container

docker stop zed          # stop the container
docker start -ai zed     # start it again and attach to its terminal
docker restart zed       # stop and start in one command
docker exec -it zed bash # open another terminal in a running container
docker logs -f zed       # follow the output of a container running in the background

Stopping a container does not delete it: the packages you installed and the files you created inside it are still there when it is started again. They are only lost when the container is removed.

docker start reuses the options given to the original docker run command. To change an option, for example to add a volume or to use another image, remove the container and create a new one with docker run.

Remove Containers

docker rm zed       # remove a stopped container
docker rm -f zed    # stop and remove a running container

Removing a container deletes everything that was written inside it and not stored in a shared folder or a volume, including the AI models and the calibration files downloaded by the ZED SDK. See Keep AI Models and Calibration Files Across Containers.

Start a Container Automatically

For an application that must start when the machine boots and restart if it crashes, run the container in the background with a restart policy:

docker run -d --restart unless-stopped --name zed-app <other_options> <your_image>

To describe several containers and their options in a single file, see Orchestrate Containers.

Manage Images

List Images

docker images                  # all the images stored on the machine
docker images stereolabs/zed   # only the ZED SDK images
docker system df               # disk space used by images, containers, volumes, and build cache

Example output of docker images stereolabs/zed:

REPOSITORY       TAG                                IMAGE ID       CREATED       SIZE
stereolabs/zed   5.5-runtime-cuda13.0-ubuntu22.04   1b7c9e3a5f20   3 weeks ago   4.9GB
stereolabs/zed   5.5-devel-cuda13.0-ubuntu22.04     6d0e2f8a4c17   3 weeks ago   12.6GB

Example output of docker system df. The RECLAIMABLE column shows the space that a cleanup can free:

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          2         1         17.5GB    12.6GB (72%)
Containers      2         1         1.4GB     1.4GB (99%)
Local Volumes   2         2         2.1GB     0B (0%)
Build Cache     24        0         3.6GB     3.6GB

The sizes above are given as an example. The columns printed by docker images can also differ slightly depending on the Docker version.

Remove Images

docker rmi stereolabs/zed:<container_tag>

An image cannot be removed while a container, even a stopped one, still uses it. In this case, Docker reports which container must be removed first:

Error response from daemon: conflict: unable to remove repository reference "stereolabs/zed:5.5-runtime-cuda13.0-ubuntu22.04" (must force) - container 8c41e0b9a6d2 is using its referenced image 1b7c9e3a5f20

Update to a New ZED SDK Version

A container always keeps the image it was created from. To move to another ZED SDK version, pull the new image and create a new container from it:

docker pull stereolabs/zed:<new_container_tag>
docker rm -f zed
docker run <same_options> --name zed stereolabs/zed:<new_container_tag>
docker rmi stereolabs/zed:<old_container_tag>   # optional, to free disk space

The AI models are specific to a ZED SDK version: after an update, the ZED SDK downloads and optimizes them again the first time they are used.

Clean Up Disk Space

ZED SDK images are several gigabytes each, so unused images and stopped containers can quickly fill the storage of an embedded device. Check what uses the space with docker system df, then remove what is no longer needed:

docker container prune   # remove all the stopped containers
docker image prune       # remove the dangling images (untagged leftovers of builds and pulls)
docker image prune -a    # remove all the images that are not used by any container
docker builder prune     # remove the build cache
docker system prune      # stopped containers, unused networks, dangling images, and build cache at once

Each command asks for confirmation before deleting anything, then reports the space it freed. For example, with docker container prune:

WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y
Deleted Containers:
8c41e0b9a6d2f5b1c3a7e9d04b6f8a2c1e3d5f7092b4a6c8e0d1f3a5b7c9e1d3
Total reclaimed space: 1.4GB

Do not add the --volumes option to docker system prune, and do not run docker volume prune, without checking the volume list first with docker volume ls. Depending on the Docker version, these commands delete the volumes that are not attached to a container, which can include the ones that store your AI models. Folders shared with -v /host/path:/container/path are never deleted by Docker.

Keep AI Models and Calibration Files Across Containers

The ZED SDK stores two kinds of data inside the container the first time it needs them:

Data	Container folder	Cost if lost
AI models (`NEURAL` depth modes, Object Detection, Body Tracking), downloaded then optimized for the GPU	`/usr/local/zed/resources/`	A new download and a new optimization, which takes several minutes per model, and much longer on an embedded device
Camera calibration files (`SN<serial_number>.conf`)	`/usr/local/zed/settings/`	A new download, which fails without an internet connection. Cameras that store their calibration on their EEPROM are not affected

Since these folders belong to the container filesystem, their content is lost when the container is removed, and every new container starts from scratch. To keep it, store the two folders on the host and share them with every container.

Add the following options to your docker run command:

-v /usr/local/zed/resources/:/usr/local/zed/resources/ \
-v /usr/local/zed/settings/:/usr/local/zed/settings/ \

For example:

docker run --gpus all -it --privileged --name zed \
  -v /usr/local/zed/resources/:/usr/local/zed/resources/ \
  -v /usr/local/zed/settings/:/usr/local/zed/settings/ \
  stereolabs/zed:<container_tag>

The first container downloads and optimizes the models into the host folder. All the following containers, including the ones created from a rebuilt image, find them there and do not download or optimize them again.

The host folders can be any folders, for example ${HOME}/zed/resources and ${HOME}/zed/settings. Docker creates them if they do not exist.
If the same ZED SDK version is installed on the host, sharing its own /usr/local/zed/resources and /usr/local/zed/settings folders lets the containers reuse the models and calibration files already present on the host.
Use a different host folder for each ZED SDK version, for example ${HOME}/zed/5.5/resources, when containers with different ZED SDK versions run on the same machine.
The same folders can be shared with several containers at the same time. See Multi-Camera Setup to avoid optimizing the same model in several containers at once.
GMSL2 cameras (ZED X, ZED X One) require additional volumes, listed in Volumes.

Use Docker Volumes

As an alternative to host folders, Docker can manage the storage itself with named volumes:

-v zed_resources:/usr/local/zed/resources/ \
-v zed_settings:/usr/local/zed/settings/ \

Named volumes are created on first use, listed with docker volume ls, and kept when the containers are removed. They are deleted only by docker volume rm, or by a volume cleanup.

Prepare the Files in Advance

On a system without an internet connection, or to avoid any download and optimization delay on the first start, prepare the content of the two folders before deploying. The Offline Deployment guide explains how to:

Download the calibration file of each camera manually.
Download and optimize the AI models manually, and copy them to another system.
Use these files in a Docker container, with shared folders or by copying them into your image.

Preparing the AI models in advance from a container requires the ZED Diagnostic tool, which is only included in the tools-devel (Jetson™) and gl-devel (desktop) images. See Choose a ZED SDK Image.

Check That the Files Are Kept

After the first run, list the shared folders on the host. The resources folder contains the downloaded file and the hidden optimized file of each AI model that was used, and the settings folder contains one file per camera:

$ ls -a /usr/local/zed/resources/
.  ..  .<model_name>_optimized-<signature>  <model_name>.model2
$ ls /usr/local/zed/settings/
SN12345678.conf

If the folders are still empty after the application used an AI model, check that the -v options were part of the docker run command that created the container:

docker inspect -f '{{ json .Mounts }}' zed

Each shared folder is listed with its host path (Source) and its container path (Destination). An empty list ([]) means that the container was created without any shared folder:

[{"Type":"bind","Source":"/usr/local/zed/resources","Destination":"/usr/local/zed/resources","Mode":"","RW":true,"Propagation":"rprivate"},{"Type":"bind","Source":"/usr/local/zed/settings","Destination":"/usr/local/zed/settings","Mode":"","RW":true,"Propagation":"rprivate"}]