DOCKER-BUILDX-IMAGETOOLS-CREATE(1)

💖 NAME 💖

okay so bestie, gather round — this is docker-buildx-imagetools-create(1), and its whole thing is: create a new image based on source images. that's the job. that's the assignment. and it ate. 💅

---

🌈 SYNOPSIS 🌈

docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]

---

🦋 DESCRIPTION 🦋

So here's the vibe: you're making a brand new manifest list out of your source manifests. ✨

Those source manifests can be manifest lists or single platform distribution manifests — and they must already exist in the registry where the new manifest is being created. like, no showing up empty-handed, the registry needs to already know them. 🙅♀️

And if you only pass in one source? create just does a carbon copy. literally a copy-paste with zero extra drama. periodt. 💖

---

🎀 OPTIONS 🎀

• --annotation=[] — add an annotation to the image
• --append[=false] — append to an existing manifest
• --dry-run[=false] — show the final image instead of pushing it
• -f, --file=[] — read the source descriptor from a file
• -h, --help[=false] — help for create
• --progress="auto" — set the type of progress output ("auto", "plain", "tty"). use plain to show container output
• -t, --tag=[] — set the reference for the new image

---

👑 OPTIONS INHERITED FROM PARENT COMMANDS 👑

• --builder="" — override the configured builder instance

---

🔥 EXAMPLE 🔥

💅 Add annotations to an image (--annotation) {#annotation}

the --annotation flag is your girl for adding annotations to the image index, the manifest, and the descriptors when you're creating a new image. 🫶

this next command creates a foo/bar:latest image with the org.opencontainers.image.authors annotation sitting pretty on the image index:

$ docker buildx imagetools create \
  --annotation "index:org.opencontainers.image.authors=dvdksn" \
  --tag foo/bar:latest \
  foo/bar:alpha foo/bar:beta foo/bar:gamma

Note 🎀 the imagetools create command supports adding annotations to the image index and descriptor, using these type prefixes: - index: - manifest-descriptor: It does not support annotating manifests or OCI layouts. 💀

want the full lore on annotations? see Annotations at /build/building/annotations/.

🌸 Append new sources to an existing manifest list (--append) {#append}

use the --append flag to append the new sources onto an existing manifest list in the destination. yes bestie, you can keep stacking. 🧚

⭐ Override the configured builder instance (--builder) {#builder}

same as /reference/cli/docker/buildx/#builder.

🙈 Show final image instead of pushing (--dry-run) {#dry-run}

use the --dry-run flag to not push the image — it just shows it to you. peek, don't yeet. 👀

🍓 Read source descriptor from a file (-f, --file) {#file}

-f FILE or --file FILE

reads source from files. a source can be a manifest digest, a manifest reference, or a JSON of OCI descriptor object. 🌈

and if you want to define annotations or extra platform properties like os.version and os.features, you need to add them into the OCI descriptor object encoded in JSON. that's the only way in, iykyk.

$ docker buildx imagetools inspect --raw alpine | jq '.manifests[0] | .platform."os.version"="10.1"' > descr.json
$ docker buildx imagetools create -f descr.json myuser/image

the descriptor in the file gets merged with the existing descriptor in the registry if it exists. 🫶

the supported fields for the descriptor are defined in the OCI spec at https://github.com/opencontainers/image-spec/blob/master/descriptor.md#properties.

💜 Set reference for new image (-t, --tag) {#tag}

-t IMAGE or --tag IMAGE

use -t or --tag to set the name of the image you're creating. name it, claim it, own it. 👑

$ docker buildx imagetools create --dry-run alpine@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907 sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204
$ docker buildx imagetools create -t tonistiigi/myapp -f image1 -f image2

---

🌈 SEE ALSO 🌈

• docker-buildx-imagetools(1)

---

and that's the whole page bestie, we're done here 💖 this one's the Apr 2025 version of docker-buildx-imagetools-create(1) — go forth and build your manifest lists, you absolute icon. 🎀✨🦋