Backup and Restore of OCI Artifacts, Images, and Repositories

Overview

The oras backup and oras restore commands together form an end-to-end solution for exporting and importing OCI artifacts between registries or into portable archives. These features are designed to support modern DevOps, security, and compliance workflows that require complete control over registry content in connected and disconnected environments.

These features are useful in the following scenarios:

Air-Gapped Environments

Organizations operating in isolated or high-security environments can use oras backup to export artifacts from a registry to local filesystem, and use oras restore to import them into an internal registry with no internet access.

Disaster Recovery and Audit Archival

You can take periodic snapshots of repositories and store them off-site. In case of accidental deletions, outages, and long-term storage to support regulatory audits, oras restore can be used to quickly recover full registry content.

Registry Migration

When moving from one container registry provider to another, the pair of commands enables a full repository export, preserving tags, manifests, layers, and referrers.

Compliance and supply chain security guarantee

Backup and restore the images along with their supply chain artifacts, such as SBOMs, signatures, vulnerability scanning reports.

Repository Duplication or Promotion

Move artifacts from dev to staging to prod registries reliably using an intermediate backup file.

Backup an entire repository to local

List all tags in the sample repository ghcr.io/chocolate-labs/oras-cli:

oras repo tags ghcr.io/chocolate-labs/oras-cli

v1.2.3
v1.2.3-2

List the referrers of the tag:

oras discover ghcr.io/chocolate-labs/oras-cli:v1.2.3

ghcr.io/chocolate-labs/oras-cli@sha256:7ab47454c95a177cbbccea9569abde6ccfd6b1367bc6407032fe78224cacc86e
├── application/vnd.cncf.notary.signature
│   └── sha256:cb90b160364b291474fc44249e59b01fd626bb25b2d8842b3345b9f3c06ea4ba
│       └── [annotations]
│           ├── io.cncf.notary.x509chain.thumbprint#S256: '[c788b80157a0cee4f7e9fb60fd533a7079181f4d74a2b62881dfbe320ccb13f9,9b1894f223d934cbd6575af3c6e1f6096b9221a7da132185f5a5cdc92235b5dc,23ffe2b8bdb9a1711515d4cffda04bc7f793d513c76c243f1020507d8669b7db]'
│           └── org.opencontainers.image.created: "2025-06-23T22:43:51Z"
├── application/vnd.in-toto+json
│   ├── sha256:b8387e1905107f771adbc5900d0d4d85ebf5c943dd83e28181acf9f1e50344a6
│   │   └── [annotations]
│   │       └── org.opencontainers.image.created: "2025-06-23T22:43:57Z"
│   └── sha256:eb87c8b2e8c24470e5c3125d60ae32071db9b89e544f6e572d42e5ede3f16a0e
│       └── [annotations]
│           └── org.opencontainers.image.created: "2025-06-23T22:44:02Z"
└── application/spdx+json
    ├── sha256:900d08c004d48ab1f792c05b69d7cbfd7c9430ba5b2712f0e5b6a4aa6893abcb
    │   └── [annotations]
    │       └── org.opencontainers.image.created: "2025-06-23T22:43:58Z"
    └── sha256:7fdcd4dce4449b9dddbaefa1bc02ba408d119c5d50227eb36ba730b3980d5e26
        └── [annotations]
            └── org.opencontainers.image.created: "2025-06-23T22:43:52Z"

Backup all tags and referrers from the sample repository and save it as a tarball using OCI image layout format:

oras backup ghcr.io/chocolate-labs/oras-cli --include-referrers --output oras-cli.tar

Found 3 tag(s) in ghcr.io/chocolate-labs/oras-cli: sha256-7ab47454c95a177cbbccea9569abde6ccfd6b1367bc6407032fe78224cacc86e, v1.2.3, v1.2.3-2
...
Pulled tag v1.2.3-2 with 5 referrer(s)
Exporting to oras-cli.tar
Exported to oras-cli.tar (32.2 MB)
Successfully backed up 3 tag(s) from "ghcr.io/chocolate-labs/oras-cli" to "oras-cli.tar" in 8s.

List the image and its referrers in the tarball to check its completeness:

oras discover --oci-layout oras-cli.tar:v1.2.3

oras-cli.tar@sha256:7ab47454c95a177cbbccea9569abde6ccfd6b1367bc6407032fe78224cacc86e
├── application/spdx+json
│   ├── sha256:7fdcd4dce4449b9dddbaefa1bc02ba408d119c5d50227eb36ba730b3980d5e26
│   │   └── [annotations]
│   │       └── org.opencontainers.image.created: "2025-06-23T22:43:52Z"
│   └── sha256:900d08c004d48ab1f792c05b69d7cbfd7c9430ba5b2712f0e5b6a4aa6893abcb
│       └── [annotations]
│           └── org.opencontainers.image.created: "2025-06-23T22:43:58Z"
├── application/vnd.in-toto+json
│   ├── sha256:b8387e1905107f771adbc5900d0d4d85ebf5c943dd83e28181acf9f1e50344a6
│   │   └── [annotations]
│   │       └── org.opencontainers.image.created: "2025-06-23T22:43:57Z"
│   └── sha256:eb87c8b2e8c24470e5c3125d60ae32071db9b89e544f6e572d42e5ede3f16a0e
│       └── [annotations]
│           └── org.opencontainers.image.created: "2025-06-23T22:44:02Z"
└── application/vnd.cncf.notary.signature
    └── sha256:cb90b160364b291474fc44249e59b01fd626bb25b2d8842b3345b9f3c06ea4ba
        └── [annotations]
            ├── io.cncf.notary.x509chain.thumbprint#S256: '[c788b80157a0cee4f7e9fb60fd533a7079181f4d74a2b62881dfbe320ccb13f9,9b1894f223d934cbd6575af3c6e1f6096b9221a7da132185f5a5cdc92235b5dc,23ffe2b8bdb9a1711515d4cffda04bc7f793d513c76c243f1020507d8669b7db]'
            └── org.opencontainers.image.created: "2025-06-23T22:43:51Z"

Restore the repository to another registry

Restore all tags and referrers from the tarball to a sample registry. Make sure you have logged in to the target registry using oras login or docker login.

note

If you want to test restoring content without pushing to the registry, use --dry-run to simulate the restore process without actually uploading any artifacts.

oras restore docker.io/myorg/oras-cli --input oras-cli.tar

Loaded backup archive: oras-cli.tar (32.2 MB)
Found 3 tag(s) in the backup: sha256-7ab47454c95a177cbbccea9569abde6ccfd6b1367bc6407032fe78224cacc86e, v1.2.3, v1.2.3-2
...
Pushed tag v1.2.3-2 with 5 referrer(s)
Successfully restored 3 tag(s) to "docker.io/myorg/oras-cli" in 31s

List the image and its referrers in the registry to check its completeness:

oras discover docker.io/myorg/oras-cli:v1.2.3

docker.io/myorg/oras-cli@sha256:7ab47454c95a177cbbccea9569abde6ccfd6b1367bc6407032fe78224cacc86e
├── application/vnd.cncf.notary.signature
│   └── sha256:cb90b160364b291474fc44249e59b01fd626bb25b2d8842b3345b9f3c06ea4ba
│       └── [annotations]
│           ├── io.cncf.notary.x509chain.thumbprint#S256: '[c788b80157a0cee4f7e9fb60fd533a7079181f4d74a2b62881dfbe320ccb13f9,9b1894f223d934cbd6575af3c6e1f6096b9221a7da132185f5a5cdc92235b5dc,23ffe2b8bdb9a1711515d4cffda04bc7f793d513c76c243f1020507d8669b7db]'
│           └── org.opencontainers.image.created: "2025-06-23T22:43:51Z"
├── application/vnd.in-toto+json
│   ├── sha256:b8387e1905107f771adbc5900d0d4d85ebf5c943dd83e28181acf9f1e50344a6
│   │   └── [annotations]
│   │       └── org.opencontainers.image.created: "2025-06-23T22:43:57Z"
│   └── sha256:eb87c8b2e8c24470e5c3125d60ae32071db9b89e544f6e572d42e5ede3f16a0e
│       └── [annotations]
│           └── org.opencontainers.image.created: "2025-06-23T22:44:02Z"
└── application/spdx+json
    ├── sha256:900d08c004d48ab1f792c05b69d7cbfd7c9430ba5b2712f0e5b6a4aa6893abcb
    │   └── [annotations]
    │       └── org.opencontainers.image.created: "2025-06-23T22:43:58Z"
    └── sha256:7fdcd4dce4449b9dddbaefa1bc02ba408d119c5d50227eb36ba730b3980d5e26
        └── [annotations]
            └── org.opencontainers.image.created: "2025-06-23T22:43:52Z"

Best Practices

• Always use --include-referrers when supply chain artifacts exist.
• Store backup files in versioned archives (e.g., backup-2025-08-01.tar).
• Use oras discover before and after to validate referrer inclusion.

For feedback and issues, visit: github.com/oras-project/oras.

For additional details, see:

• User Scenarios
• Backup/Restore Proposal