---
title: How to Push SOCI-Enabled Images to Your Container Registry
description: Convert container images into SOCI-enabled images and push them to DigitalOcean Container Registry to support lazy loading.
product: Container Registry
url: https://docs.digitalocean.com/products/container-registry/how-to/push-soci-images/
last_updated: "2026-08-10"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# How to Push SOCI-Enabled Images to Your Container Registry

The DigitalOcean Container Registry (DOCR) is a private Docker image registry that lets you store and manage private container images. DOCR integrates natively with Docker environments and DigitalOcean Kubernetes clusters.

DigitalOcean Container Registry (DOCR) supports pushing *SOCI-enabled* images to your registry. A Seekable OCI (SOCI) index lets SOCI-aware container runtimes start containers in seconds by streaming image layers on demand instead of downloading the entire image first. This is especially useful for large images, such as AI and machine learning images that are several gigabytes in size.

SOCI v2 works by converting an existing image into a SOCI-enabled image with the index built in. The converted image is still a standard OCI image: runtimes without SOCI support, such as plain Docker, pull and run it as a normal image, while SOCI-aware runtimes get lazy loading.

There are two ways to create and push a SOCI-enabled image. The standalone workflow uses `skopeo` and the `soci` CLI and does not require `containerd`, so it works on any machine, including CI runners and build hosts. The `containerd` workflow uses `nerdctl` on a host that is already [set up with the SOCI snapshotter](https://docs.digitalocean.com/products/container-registry/how-to/pull-mirror-images/index.html.md#set-up-a-host-for-soci-lazy-loading).

## Prerequisites

- A [container registry](https://docs.digitalocean.com/products/container-registry/how-to/create-registry/index.html.md).
- A [personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) with registry read and write access.
- For the standalone workflow: [`skopeo`](https://github.com/containers/skopeo) and the [`soci` CLI](https://github.com/awslabs/soci-snapshotter) version 0.13 or later.
- For the `containerd` workflow: a host with `nerdctl` and the SOCI snapshotter installed.

Pushed images are subject to the [Container Registry limits](https://docs.digitalocean.com/products/container-registry/details/limits/index.html.md) on image and layer size.

## Convert and Push an Image Using `skopeo`

The standalone workflow copies the source image to a local directory, converts it, and pushes the result without requiring a container runtime on the machine.

First, copy the source image into a local OCI layout directory:

```shell
skopeo copy docker://<source-image>:<tag> oci:./src-dir:<tag>
```

Then, convert the image into a SOCI-enabled image:

```shell
soci convert --standalone --format oci-dir ./src-dir ./out-dir
```

The `--standalone` flag builds the SOCI index without requiring a containerd content store, and `--format oci-dir` writes the converted image to a local OCI layout directory.

Finally, push the converted image to your registry. `skopeo` authenticates with your personal access token as both the username and the password:

```shell
skopeo copy --dest-creds "<your-api-token>:<your-api-token>" \
  oci:./out-dir:<tag> \
  docker://registry.digitalocean.com/<your-registry>/<image>:<tag>
```

## Convert and Push an Image Using `nerdctl`

On a `containerd` host with `nerdctl` and the SOCI snapshotter installed, you can convert and push without an intermediate directory.

First, log in to the registry with your personal access token as both the username and the password, then pull the source image:

```shell
nerdctl login registry.digitalocean.com -u <your-api-token> -p <your-api-token>
nerdctl pull <source-image>:<tag>
```

Then, convert the image and tag it with its destination path in your registry:

```shell
soci convert <source-image>:<tag> registry.digitalocean.com/<your-registry>/<image>:<tag>
```

Finally, push the converted image:

```shell
nerdctl push registry.digitalocean.com/<your-registry>/<image>:<tag>
```

## Pull Behavior of SOCI-Enabled Images

Because a SOCI-enabled image is a standard OCI image, anyone with access to your registry can pull it with Docker or any other OCI-compatible tooling and get a normal, full-download image. Hosts that run a SOCI-aware runtime, such as `nerdctl` with the SOCI snapshotter, get lazy loading automatically. To set up a host for lazy pulls, see [How to Pull AI Images from DOCR Mirror Registries](https://docs.digitalocean.com/products/container-registry/how-to/pull-mirror-images/index.html.md#set-up-a-host-for-soci-lazy-loading).