---
title: How to Pull AI Images from DOCR Mirror Registries
description: Pull popular AI container images from DigitalOcean's regional mirror registries using Docker or SOCI lazy loading.
product: Container Registry
url: https://docs.digitalocean.com/products/container-registry/how-to/pull-mirror-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 Pull AI Images from DOCR Mirror Registries

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) provides *mirror registries*: DigitalOcean-curated regional mirrors of popular AI container images. Pulling from a mirror registry in the same datacenter region as your infrastructure keeps image downloads region-local and avoids rate limits on upstream registries.

Mirror registries are read-only and shared by all DigitalOcean customers. You do not push images to them, and they do not count against your registry’s storage. Pulling from a mirror registry requires a [DigitalOcean personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) with registry read access; it does not require a Container Registry subscription.

## Available Images and Regions

Mirror registries host the following images:

| Image | Upstream Source | Mirrored Tags |
|---|---|---|
| `nvidia/pytorch` | [nvcr.io](https://catalog.ngc.nvidia.com/orgs/nvidia/containers/pytorch) | `24.05-py3`, `26.03-py3`, `26.04-py3`, `26.05-py3` |
| `rocm/pytorch` | [Docker Hub](https://hub.docker.com/r/rocm/pytorch) | `latest` |

The image catalog grows over time. The `nvidia/pytorch` image has no `latest` tag because upstream NGC publishes versioned tags only, so always specify a versioned tag. The mirrored `rocm/pytorch:latest` image reflects the upstream `latest` tag as of the last mirror sync, so it may lag behind the current upstream image.

All mirrored images are built for the `linux/amd64` platform only.

Each region has its own mirror registry, named `docr-mirror-<region>-registry`. The full path to an image is:

```text
registry.digitalocean.com/docr-mirror-<region>-registry/<image>:<tag>
```

For example, the path to the `nvidia/pytorch:24.05-py3` image in the NYC3 mirror is `registry.digitalocean.com/docr-mirror-nyc3-registry/nvidia/pytorch:24.05-py3`.

Mirror registries are available in the following datacenter regions: `nyc3`, `atl1`, `sfo2`, `sfo3`, `tor1`, `lon1`, `ams3`, `fra1`, `blr1`, `sgp1`, and `syd1`. The mirrored images are identical in every region. Pull from the region closest to your infrastructure for the best download speed.

## Log In to the Mirror Registry

To authenticate, log in to `registry.digitalocean.com` using a [personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) with registry read access as both the username and the password:

```shell
docker login registry.digitalocean.com -u <your-api-token> -p <your-api-token>
```

If you use `nerdctl`, run `nerdctl login` with the same arguments.

## Pull an Image with Docker

Mirror images are standard OCI images, so you can pull them with Docker or any other OCI-compatible tooling with no additional setup:

```shell
docker pull registry.digitalocean.com/docr-mirror-nyc3-registry/nvidia/pytorch:24.05-py3
```

A standard pull downloads the full image, which is approximately 8.5 GB for `nvidia/pytorch`. To start containers before the full image finishes downloading, use SOCI lazy loading instead.

Because mirrored images are `linux/amd64` only, pulling on an ARM machine, such as an Apple silicon Mac, fails with a `no matching manifest` error unless you add the `--platform` flag:

```shell
docker pull --platform linux/amd64 registry.digitalocean.com/docr-mirror-nyc3-registry/nvidia/pytorch:24.05-py3
```

Pulls on `amd64` hosts, such as Droplets and GPU nodes, do not need the flag.

## Set Up a Host for SOCI Lazy Loading

Mirror images are *SOCI-enabled*: they include a Seekable OCI (SOCI) index that lets a SOCI-aware container runtime start a container in seconds and stream image layers on demand instead of downloading the entire image up front.

SOCI lazy loading requires a one-time setup on each host that pulls images. The host must be a Linux `amd64` machine, such as a [Droplet](https://docs.digitalocean.com/products/droplets/index.html.md), with `containerd` 1.4 or later and root access.

**Note**:

  If the SOCI snapshotter is not installed and running, `nerdctl --snapshotter soci pull` silently falls back to a full download. Complete the setup below to get lazy loading.

### Install `nerdctl` and the SOCI Snapshotter

Install `fuse`, which the snapshotter uses to mount layers lazily:

```shell
sudo apt-get update && sudo apt-get install -y fuse
```

Download and install `nerdctl` version 1.6.0 or later. The following example installs version 2.1.5:

```shell
NERDCTL_VER=2.1.5
curl -fsSL https://github.com/containerd/nerdctl/releases/download/v${NERDCTL_VER}/nerdctl-${NERDCTL_VER}-linux-amd64.tar.gz \
  | sudo tar -C /usr/local/bin -xz nerdctl
```

Then, download and install the `soci` CLI and snapshotter daemon:

```shell
SOCI_VER=0.13.0
curl -fsSL https://github.com/awslabs/soci-snapshotter/releases/download/v${SOCI_VER}/soci-snapshotter-${SOCI_VER}-linux-amd64.tar.gz \
  | sudo tar -C /usr/local/bin -xz soci soci-snapshotter-grpc
```

SOCI requires running `nerdctl` as root. Rootless `nerdctl` installations are not supported and ignore the SOCI snapshotter.

### Run the Snapshotter as a Service

Create a systemd unit so the snapshotter daemon starts on boot and restarts on failure. Create the service file:

```shell
sudo tee /etc/systemd/system/soci-snapshotter.service <<'EOF'
[Unit]
Description=SOCI snapshotter
After=network.target

[Service]
ExecStart=/usr/local/bin/soci-snapshotter-grpc
Restart=always

[Install]
WantedBy=multi-user.target
EOF
```

Then, enable and start the service:

```shell
sudo systemctl enable --now soci-snapshotter
```

### Register the Snapshotter with containerd

`containerd` needs a proxy plugin entry to use the snapshotter. Open the `containerd` configuration file:

```shell
sudo nano /etc/containerd/config.toml
```

Add the following section to the file:

```toml
[proxy_plugins.soci]
  type = "snapshot"
  address = "/run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock"
```

Then, restart `containerd`:

```shell
sudo systemctl restart containerd
```

Optionally, make `soci` the default snapshotter for `nerdctl` so you do not need to pass `--snapshotter soci` with every command:

```shell
sudo mkdir -p /etc/nerdctl
echo 'snapshotter = "soci"' | sudo tee -a /etc/nerdctl/nerdctl.toml
```

### Verify the Snapshotter

Confirm that `nerdctl` can see the snapshotter:

```shell
sudo nerdctl system info | grep -i storage
```

The output must include `soci` in the list of storage plugins:

```text
Output
 Storage: native overlayfs soci
```

Also confirm that the snapshotter’s socket exists:

```shell
ls /run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock
```

## Pull an Image with SOCI Lazy Loading

After setting up the host, pull an image with the `soci` snapshotter:

```shell
sudo nerdctl --snapshotter soci pull \
  registry.digitalocean.com/docr-mirror-nyc3-registry/nvidia/pytorch:24.05-py3
```

The pull fetches only the image index and metadata, which is tens of kilobytes, and completes in seconds. The rest of the image streams on demand when a container runs.

Lazily pulled images report a local size of `0B` in `nerdctl images` output. This is expected because the layers have not been downloaded yet.

You can also pull and run in one step. For example, to verify the PyTorch version in the image:

```shell
sudo nerdctl --snapshotter soci run --rm --network host \
  registry.digitalocean.com/docr-mirror-nyc3-registry/nvidia/pytorch:24.05-py3 \
  python -c "import torch; print(torch.__version__)"
```

To run a GPU workload on a host with NVIDIA drivers installed, add the `--gpus all` flag:

```shell
sudo nerdctl --snapshotter soci run --rm --gpus all --network host \
  registry.digitalocean.com/docr-mirror-nyc3-registry/nvidia/pytorch:24.05-py3 \
  python -c "import torch; print(torch.cuda.is_available())"
```

## Troubleshooting

| Symptom | Resolution |
|---|---|
| Lazy pull is slow or downloads the full image | The snapshotter is not running or the `--snapshotter soci` flag was omitted. [Verify the snapshotter](#verify-the-snapshotter). |
| `soci` is missing from `nerdctl system info` storage plugins | The `[proxy_plugins.soci]` entry is missing from `/etc/containerd/config.toml`, or `containerd` was not restarted after the change. |
| `fuse: device not found` | `fuse` is not installed. Install it and retry. |
| Lazy pull works but container startup is slow | The snapshotter daemon stopped and `containerd` fell back to full pulls. Check `systemctl status soci-snapshotter`. |
| `401 Unauthorized` | The personal access token lacks registry read access, or the registry path is incorrect. |
| Rootless `nerdctl` ignores SOCI | SOCI requires `nerdctl` to run as root. Run commands with `sudo`. |

To push your own SOCI-enabled images to your registry, see [How to Push SOCI-Enabled Images to Your Container Registry](https://docs.digitalocean.com/products/container-registry/how-to/push-soci-images/index.html.md).