Introduction

A multi-architecture container image is not just one image layer set with a new tag. It is usually a manifest list, or image index, that points to separate images for platforms such as linux/amd64 and linux/arm64. If you copy only one platform image, you lose the multi-arch behavior.

So the real task is not “push the tag somewhere else.” It is “copy the index and all referenced platform images together.”

Why a Normal Pull and Push Can Be Incomplete

If you run a normal docker pull on one machine and then docker push to another registry, you often copy only the image for the host architecture you pulled. For example, pulling on an amd64 laptop usually does not fetch the arm64 variant.

That is why tools that understand remote registries and manifest lists are preferable. They copy the multi-arch structure directly instead of relying on a local single-platform image cache.

Use skopeo copy --all

skopeo is one of the cleanest tools for this job because it copies directly from registry to registry.

skopeo copy --all \
  docker://source.example.com/team/app:1.2.3 \
  docker://target.example.com/team/app:1.2.3

The important flag is --all. It tells skopeo to copy every image referenced by the manifest list, not just one platform.

If authentication is needed, log in first or provide credentials through supported auth configuration.

Verify the Result

After the copy, inspect the target image and confirm that both the index and the platform entries exist.

docker buildx imagetools inspect target.example.com/team/app:1.2.3

A correct result shows multiple platform entries, for example:

• 'linux/amd64'
• 'linux/arm64'

Verification matters because a tag can exist in the destination registry while still being incomplete.

An Alternative with regctl

Another good registry-focused option is regctl.

regctl image copy \
  source.example.com/team/app:1.2.3 \
  target.example.com/team/app:1.2.3

This is useful when you want registry-native operations without loading images into the local Docker daemon. As with skopeo, the benefit is that the tool understands image indexes and remote copying.

When docker buildx imagetools create Helps

If your goal is to assemble or retag an already existing multi-platform image set, docker buildx imagetools create can also help.

docker buildx imagetools create \
  --tag target.example.com/team/app:1.2.3 \
  source.example.com/team/app:1.2.3

This approach is useful when the source registry already contains a correct multi-arch image and you want a new reference in another location. It is not the same as building the images again.

Think About Registry Constraints

Not every registry behaves the same way. Before copying, confirm:

• the destination supports OCI image indexes or Docker manifest lists
• credentials allow both read access on the source and write access on the target
• repository naming rules match your target path
• retention or immutability policies will not reject the new tag

Operationally, these issues cause more failures than the copy command itself.

Common Pitfalls

• Pulling and pushing from a single-architecture machine and assuming the multi-arch manifest came along automatically.
• Forgetting the --all behavior when using registry-copy tooling.
• Verifying only that the tag exists, instead of inspecting whether the destination still contains all platform variants.
• Copying into a registry that does not support the required manifest format.
• Reusing credentials that can read the source registry but cannot create the repository or tag in the destination.

Summary

• A multi-arch image is an index plus multiple platform-specific images.
• A normal single-platform pull and push often loses the full multi-arch structure.
• 'skopeo copy --all is a reliable way to copy everything between registries.'
• Always inspect the destination image after the copy to confirm platform coverage.
• The hardest failures are usually registry permissions and manifest-format support, not the copy syntax.