OCI-DELTA(1)(oci-delta)

🌸 NAME 🌸

oci-delta — bestie, this lil icon makes delta files between OCI image archives, and applies them too 💖

ok so quick vibe check: this is the oci-delta page from the oci-delta manual (section 1). sit down, grab a strawberry 🍓, we're gonna go through everything.

---

✨ SYNOPSIS ✨

oci-delta subcommand [OPTIONS] [ARGUMENTS]

oci-delta create [-s|--statistics] [--log-level LEVEL] [--debug] [-q|--quiet] [-j|--jobs N] [--binary-diff METHOD] [--signature FILE] old-image new-image output

oci-delta apply [--ostree-repo PATH] [--directory PATH] [--container-storage PATH] [--verify-key FILE] [--log-level LEVEL] [--debug] [-q|--quiet] delta-file output

oci-delta import [--container-storage PATH] [-t|--tag NAME] [--verify-key FILE] [--log-level LEVEL] [--debug] [-q|--quiet] delta-file

---

🦋 DESCRIPTION 🦋

okay so oci-delta creates and applies delta files between OCI image archives for bootc systems. and the way that delta files are significantly smaller than full OCI archives?? because they exclude layers that are already present on the target system, and they use binary diffs (tar-diff) for the changed layers. lowkey genius, no cap 🔥

This tool operates on OCI image archives and supports three modes of operation: creating deltas between two images, applying deltas to reconstruct full images, and directly importing deltas into container storage. three modes, three moods, all slaying 💅

Delta files are OCI artifacts, which means they can be stored in registries or distributed via removable media for air-gapped environments. usb stick girlies, this one's for you 🫶

---

👑 SUBCOMMANDS 👑

🎀 create

Create a delta between two OCI images. main character energy fr fr.

Syntax:

oci-delta create [OPTIONS] old-image new-image output

Arguments:

• old-image — the old/source image. supported formats are oci-archive:/PATH, oci:/PATH, or containers-storage:/REF. if you don't give a type prefix, oci-archive is what it assumes. it's giving default behavior ✨
• new-image — the new/target image (same format as old-image, matching outfits 💖).
• output — the output delta file (oci-archive:PATH or oci:PATH).

Options:

• -s, --statistics — show statistics after delta creation, including layer counts and bytes saved. the receipts, bestie 🧾
• --log-level=LEVEL — log verbosity level: error, warn, info, or debug (default: info).
• --debug — show detailed progress information during delta creation (shorthand for --log-level=debug).
• -q, --quiet — suppress all output except errors (shorthand for --log-level=error). silent mode, mysterious era 💀
• -j, --jobs=N — maximum number of parallel tar-diff workers (default: number of CPUs). multitasking queen.
• --binary-diff=METHOD — per-file binary diff backend: bsdiff (default), zstd, or auto. auto uses zstd under the zstd size cap, then bsdiff under the bsdiff cap. it literally picks for you, iconic.
• --compression-level=N — outer tar-diff zstd level (0 = tar-diff default).
• --zstd-diff-level=N — zstd level for dictionary patches (-1 = use --compression-level / tar-diff default).
• --zstd-diff-window=N — zstd window size in MiB for dictionary patches. 0 (default) sizes the window automatically from the source file. a non-zero value must be a power of two and at most 512. read that again, bestie 📏
• --max-zstd-diff-size=N — max file size in MiB for zstd dictionary patches (default: 128; 0 = no extra cap). files over this cap skip zstd. bye 👋
• --max-bsdiff-size=N — max file size in MiB for bsdiff (default: 192; 0 = no limit).
• --signature=FILE — signature OCI artifact to embed in the delta. can be specified multiple times to embed multiple signatures. this enables offline signature verification during apply/import. stack those sigs, it's giving security 💜

🌈 apply

Apply a delta to reconstruct a full OCI image archive. glow-up complete ✨

Syntax:

oci-delta apply [OPTIONS] delta-file output

Arguments:

• delta-file — path to the delta file to apply.
• output — output image (oci-archive:PATH or oci:PATH). if no type prefix is given, oci-archive is used.

Options:

• --ostree-repo=PATH — OSTree repository path for delta source data (default: /ostree/repo). auto-detects the source image ref via config digest. the --ostree-repo is the default on bootc systems. lowkey the hometown hero 🏠
• --directory=PATH — source directory containing layer files for delta reconstruction. alternative to --ostree-repo.
• --container-storage=PATH — podman container storage root for delta reconstruction. alternative to --ostree-repo.
• --verify-key=FILE — path to cosign public key in PEM format for signature verification. if specified, the delta's embedded signature will be verified before applying. trust but verify, periodt 🔐
• --log-level=LEVEL — log verbosity level: error, warn, info, or debug (default: info).
• --debug — show detailed progress information during delta application (shorthand for --log-level=debug).
• -q, --quiet — suppress all output except errors (shorthand for --log-level=error).

🚨 note: --ostree-repo, --directory, and --container-storage are mutually exclusive. only one source type can be specified. pick ONE, bestie, this is not a choose-multiple situation 🙈

💖 import

Apply a delta and import the result directly into container storage. straight into the vault, no detours 💅

Syntax:

oci-delta import [OPTIONS] delta-file

Arguments:

• delta-file — path to the delta file to import.

Options:

• --container-storage=PATH — podman container storage root (default: system default location).
• -t, --tag=NAME — tag name for the imported image (e.g., myimage:latest). name her 💖
• --verify-key=FILE — path to cosign public key in PEM format for signature verification.
• --log-level=LEVEL — log verbosity level: error, warn, info, or debug (default: info).
• --debug — show detailed progress information during import (shorthand for --log-level=debug).
• -q, --quiet — suppress all output except errors (shorthand for --log-level=error).

After a successful import, the image ID is printed to stdout and can be used with podman or other container tools. so you can just grab it and go 🎀

---

⭐ EXIT STATUS ⭐

1. 0 — Success. the operation completed without errors. we ate and left no crumbs 🍽️
2. 1 — An error occurred. error details are written to stderr. not the vibe, but at least it tells you why 😭

---

🌸 EXAMPLES 🌸

Create a delta between two OCI archives:

$ oci-delta create old.oci-archive new.oci-archive update.oci-delta

Create a delta with statistics:

$ oci-delta create --statistics old.oci new.oci delta.oci

Delta creation statistics:
  Old image layers: 15
  New image layers: 16
  Processed layers: 8
  Skipped layers:   7
  Processed layer bytes:  125829120
  Tar-diff layer bytes:   8388608
  Original layer bytes:   12582912
  Bytes saved:            104857600 (83.3%)

look at those numbers. 83.3% saved?? that's not a glow-up that's a full transformation 💅

Apply a delta on a bootc system:

$ oci-delta apply update.oci-delta new.oci-archive
$ bootc switch --transport=oci-archive new.oci-archive
$ rm new.oci-archive

Import a delta directly into container storage:

$ oci-delta import --tag myapp:v2.0 update.oci-delta
sha256:abc123...
$ podman images
REPOSITORY    TAG       IMAGE ID      CREATED        SIZE
myapp         v2.0      abc123...     1 minute ago   500 MB

Create delta with embedded signature:

$ oci-delta create --signature signature.oci \
    old.oci new.oci delta.oci

Apply delta with signature verification:

$ oci-delta apply --verify-key cosign.pub \
    signed-delta.oci output.oci

Air-gapped USB workflow:

# On internet-connected system: create delta
$ oci-delta create \
    containers-storage:registry.io/app:v1.0 \
    containers-storage:registry.io/app:v2.0 \
    /mnt/usb/app-update.delta

# Transfer USB drive to air-gapped system

# On air-gapped bootc system: apply and install
$ oci-delta apply /mnt/usb/app-update.delta app-v2.oci
$ bootc switch --transport=oci-archive app-v2.oci
$ reboot

Use container storage as delta source:

$ oci-delta apply --container-storage /var/lib/containers/storage \
    delta.oci output.oci

Use custom directory as delta source:

$ oci-delta apply --directory /path/to/layers \
    delta.oci output.oci

---

🧚 FILES 🧚

• /ostree/repo — default OSTree repository path for delta source data on bootc systems. layer files from installed images are stored as objects under this directory. her natural habitat 🌳
• /var/tmp/oci-delta-* — temporary working directories created during delta operations. automatically cleaned up on successful completion. she cleans up after herself, we love a tidy queen 🧹
• /var/lib/containers/storage — default podman container storage location (system default).

---

💜 REQUIREMENTS 💜

The target system must run bootc version 1.15.0 or later for proper layer deduplication using diff_ids. no old bootc, bestie, upgrade or perish 🚨

---

🌈 SEE ALSO 🌈

• bootc(8)
• podman(1)
• ostree(1)
• cosign(1)

Project homepage: ⟨https://github.com/containers/oci-delta⟩

Delta file format specification: see README.md in the source repository.

---

💅 AUTHORS 💅

oci-delta was written by the Containers organization. absolute legends, we stan 🫶

See MAINTAINERS.md in the source repository for the current list of maintainers.

---

🎀 COPYRIGHT 🎀

Copyright © 2026 the oci-delta authors.

Licensed under the Apache License, Version 2.0.

---

and that's the whole page, bestie 💖 this was version 0.2.0, dated June 2026, from the oci-delta crew — go make some tiny deltas, ily, bye ✨🦋