> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.stereolabs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.stereolabs.com/_mcp/server. # Manage ZED SDK Containers and Images > Choose the right ZED SDK Docker image, then list, stop, remove, and clean up containers and images, and keep AI models and calibration files across containers. 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](https://hub.docker.com/r/stereolabs/zed/tags/) 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](/docs/integrations/docker/create-docker-images#optimize-your-image-size), 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](/docs/integrations/docker/install-on-linux#download-a-zed-sdk-docker-image). * **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. > **Note** > > 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](/docs/integrations/docker/install-on-linux#download-a-zed-sdk-docker-image) and [Install on NVIDIA® Jetson™](/docs/integrations/docker/install-on-nvidia-jetson#download-a-zed-sdk-docker-image) 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: **`Desktop`** ```bash Desktop docker run --gpus all -it --privileged --name zed stereolabs/zed: ``` **`Jetson`** ```bash Jetson docker run --runtime nvidia -it --privileged --name zed stereolabs/zed: ``` 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](#remove-containers). To create a temporary container that is deleted automatically as soon as it exits, add the `--rm` option. ### List Containers ```bash 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: ```txt 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 ```bash 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. > **Note** > > `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 ```bash docker rm zed # remove a stopped container docker rm -f zed # stop and remove a running container ``` > **Warning** > > 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](#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: ```bash docker run -d --restart unless-stopped --name zed-app ``` To describe several containers and their options in a single file, see [Orchestrate Containers](/docs/integrations/docker/orchestrate-containers). ## Manage Images ### List Images ```bash 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`: ```txt 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](#clean-up-disk-space) can free: ```txt 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 ``` > **Note** > > 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 ```bash docker rmi stereolabs/zed: ``` 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: ```txt 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: ```bash docker pull stereolabs/zed: docker rm -f zed docker run --name zed stereolabs/zed: docker rmi stereolabs/zed: # 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: ```bash 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`: ```txt 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 ``` > **Warning** > > 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.conf`) | `/usr/local/zed/settings/` | A new download, which fails without an internet connection. Cameras that [store their calibration on their EEPROM](/docs/development/zed-sdk/offline-deployment#option-2-use-the-calibration-stored-on-the-camera-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. ### Share Host Folders Add the following options to your `docker run` command: ```bash -v /usr/local/zed/resources/:/usr/local/zed/resources/ \ -v /usr/local/zed/settings/:/usr/local/zed/settings/ \ ``` For example: **`Desktop`** ```bash Desktop 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: ``` **`Jetson`** ```bash Jetson docker run --runtime nvidia -it --privileged --name zed \ -v /usr/local/zed/resources/:/usr/local/zed/resources/ \ -v /usr/local/zed/settings/:/usr/local/zed/settings/ \ stereolabs/zed: ``` 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](/docs/integrations/docker/multi-camera-setup#cache-ai-models-and-calibration-files-across-containers) to avoid optimizing the same model in several containers at once. * [GMSL2](/docs/products/embedded/zed-link-capture-card/gmsl2#what-is-gmsl2) cameras (ZED X, ZED X One) require additional volumes, listed in [Volumes](/docs/integrations/docker/create-docker-images#volumes). ### Use Docker Volumes As an alternative to host folders, Docker can manage the storage itself with named volumes: ```bash -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](#clean-up-disk-space). ### 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](/docs/development/zed-sdk/offline-deployment) guide explains how to: * [Download the calibration file](/docs/development/zed-sdk/offline-deployment#calibration-files) of each camera manually. * [Download and optimize the AI models](/docs/development/zed-sdk/offline-deployment#ai-models) manually, and copy them to another system. * [Use these files in a Docker container](/docs/development/zed-sdk/offline-deployment#docker-containers), with shared folders or by copying them into your image. > **Note** > > 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](#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: ```txt $ ls -a /usr/local/zed/resources/ . .. ._optimized- .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: ```bash 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: ```txt [{"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"}] ```