Push a Docker Manifest List Without Losing the Local Reference

You will publish an existing Docker manifest list to its repository, check the result, and keep the local manifest reference available for another attempt. Allow about ten minutes, plus the time needed for the registry to accept the image data. This guide uses Docker 29.8.1, installed here as the docker-ce-cli command. The command is still marked experimental, so check the installed help on the machine where you run it.

A manifest list is not an ordinary image tag that you build with this command. It is a local manifest-list reference that already points at one or more platform-specific images. The push command publishes that list and its referenced manifests to the registry named by the reference.

1. Check the installed command

First confirm the Docker client and the exact interface available to your shell. This is an ordinary, read-only check and does not need elevated privileges:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker manifest push --help
Usage:  docker manifest push [OPTIONS] MANIFEST_LIST

Push a manifest list to a repository

Options:
      --insecure   Allow push to an insecure registry
  -p, --purge      Remove the local manifest list after push

Your build identifier can differ. The useful checks are that the subcommand exists, its usage ends with a manifest-list argument, and the options match the operation you intend to perform.

2. Confirm the local manifest list

Use the exact local reference that was used when the list was created. A common shape is registry.example.com/acme/widget:release-2026-09. Inspect it before pushing:

$ docker manifest inspect registry.example.com/acme/widget:release-2026-09

Successful output is JSON describing the manifest list or image index. It should include the platforms you expect, such as separate Linux amd64 and arm64 entries. The repository and tag in this command are placeholders: replace them with a reference that exists in your local Docker manifest store.

Checkpoint: do not continue until you can identify the destination registry, repository, tag, and intended platforms. A typo in the reference can send a valid push to the wrong repository or produce a misleading not-found error.

3. Authenticate to the destination registry

Log in using your registry's normal credential workflow before pushing. The login command is separate from docker manifest push and may update Docker's credential configuration, so follow your organisation's secret-handling rules. Do not put a password or access token directly in a shell command or in a guide copied into a ticket.

$ docker login registry.example.com
Username: YOUR_REGISTRY_USER
Password: [enter securely when prompted]
Login Succeeded

Login normally requires no root privileges. Use sudo only if your Docker installation specifically requires it; mixing root and non-root Docker configuration can make credentials appear to be missing because the two users may read different config files.

4. Push without deleting the local list

Run the command with the fully qualified manifest-list reference:

$ docker manifest push registry.example.com/acme/widget:release-2026-09
sha256:REPOSITORY_MANIFEST_DIGEST

The digest printed by a successful client is a content identifier for the pushed repository manifest. Exact progress and digest output can vary by Docker build and registry. Save the exit status in automation, rather than treating a line of output as proof of success:

$ docker manifest push registry.example.com/acme/widget:release-2026-09
$ push_status=$?
$ printf 'push exit status: %s\n' "$push_status"
push exit status: 0

Without --purge, the local manifest-list reference is retained after a successful push. That is the safer default for a first attempt because you can inspect it again or retry after diagnosing a registry problem.

5. Verify the remote reference

Ask the registry for the reference after the push:

$ docker manifest inspect registry.example.com/acme/widget:release-2026-09

Compare the returned platforms and digest with what you expected. If your registry or Docker version prints a different JSON shape, check for the same facts rather than matching the complete output byte for byte. A successful push does not make an incorrectly assembled manifest list correct; it only publishes what was referenced locally.

For a deployment pipeline, keep the image references immutable where possible. Record the tag and digest in the release record, and have the deployment system verify that the remote reference is the one it was given. Do not use a mutable tag as the sole audit record for a production release.

6. Use an insecure registry only as an explicit exception

The --insecure option tells Docker to allow a push to an insecure registry. Use it only when the registry is deliberately configured for that mode and the network is controlled. It can permit transport without the normal TLS protection, so it is a security-sensitive choice, not a general fix for authentication failures.

$ docker manifest push --insecure registry.example.com:5000/acme/widget:release-2026-09

Prefer fixing the registry certificate, hostname, trust store, or authentication configuration. Never add --insecure to a reusable script just because a normal push failed. If you must use it for a local test registry, keep the exception scoped to that one command and do not publish credentials or production images through the test endpoint.

7. Decide whether to purge the local list

The optional --purge or -p flag removes the local manifest list after the push:

$ docker manifest push --purge registry.example.com/acme/widget:release-2026-09

This changes local Docker state and is not needed to publish the list. Treat it as a cleanup action only after remote verification has succeeded and you have no need to retry from the local reference. It does not undo the remote push. There is no rollback operation in this command that removes a manifest from the registry.

If you purged too early, recreate the manifest list from the original platform-specific image references using your normal build or release procedure, then inspect it before pushing again. Keep those source image references and the release metadata until the remote result has been checked.

8. Diagnose the likely failures

A not-found error usually means the local manifest reference is absent, the tag is mistyped, or the client is looking at a different Docker context or user configuration. Repeat docker manifest inspect with the exact reference and check docker context show before changing anything.

An unauthorised or denied error points to registry credentials or repository permissions. Re-authenticate to the exact hostname in the reference and confirm that the account can push to that repository. Do not respond by adding --insecure; that flag changes registry transport handling, not authorisation.

If one platform is missing, stop the release and inspect the local manifest list rather than pushing repeatedly. The push command does not add platforms or repair a list. If the registry rejects a referenced image, ensure every child manifest is available at the expected repository and that your account can read it.