docker load command to import the tarball and then run it by explicitly specifying the correct platform variant using the --platform flag. This ensures that the container engine selects the appropriate binary for your host's CPU architecture, such as linux/amd64 or linux/arm64, rather than attempting to run an incompatible version.
Understanding Multiarchitecture Images
Docker images can now contain multiple variants for different processor architectures within a single manifest file. This is often referred to as a "manifest list" or "multi-arch image." When you pull an image from a registry like Docker Hub without specifying a platform, Docker automatically detects your host's architecture and downloads the corresponding layer. However, when working with pre-downloaded image archives (tarballs), this automatic selection does not happen during the load phase. The archive may contain binaries for several architectures, but the local daemon needs explicit instructions on which one to activate.
This capability is crucial for developers building cross-platform applications. For instance, a developer might build an image on an Apple Silicon Mac (ARM64) and need to deploy it on a Linux server (AMD64). Without proper handling, simply loading the image might result in errors if the default loaded variant does not match the execution environment. Understanding this mechanism prevents deployment failures and ensures consistency across diverse hardware setups.
Exporting the Image Correctly
Before you can load a multiarchitecture image, it must be exported correctly from the source machine. The standard docker save command preserves the multi-arch manifest structure. If you export the image incorrectly, you might lose the platform-specific metadata required for later selection.
- Identify the Image: Ensure you have the correct image tag or ID on the source machine. You can list images using
docker images. - Save the Image: Use the following command to create a tarball. Replace
myimage:tagwith your actual image reference.
docker save myimage:tag -o myimage.tarThis command creates a single .tar file containing all layers and the manifest. It is important to transfer this file to the target machine intact. Any corruption during transfer will prevent successful loading. Note that while some tools allow exporting individual platforms, keeping the full multi-arch manifest allows greater flexibility on the destination side.
Related Resource
If you are setting up the network environment for these containers, see How to Connect a Dockerised NodeJS Server Application to External Clients and Databases for guidance on networking configurations.
Loading the Image Archive
Once the .tar file is on the target machine, you need to import it into the local Docker image store. The process involves two distinct steps: loading the data into the storage backend and then ensuring the correct variant is tagged for use.
First, execute the docker load command. This imports all the image layers and metadata into the Docker daemon. It does not immediately create a runnable container; it merely makes the image available locally.
docker load -i myimage.tarAfter running this, you can check your local images with docker images. You might notice that the image appears, but sometimes the tags are not fully resolved for immediate execution depending on how the manifest was structured. More importantly, the daemon now holds the multi-arch manifest. At this stage, you have the data, but you still need to specify which architecture to use when running the container.
Running with the Correct Platform
The critical step that distinguishes handling multiarchitecture images from standard ones is the use of the --platform flag during container creation. Even though the image is loaded, Docker requires you to explicitly state the target architecture if the image contains multiple variants.
To run the container, append the platform specification to your docker run command. Common values include linux/amd64 for Intel/AMD 64-bit processors and linux/arm64 for ARM-based processors like those in Raspberry Pi or newer Macs.
docker run --platform linux/amd64 myimage:tagIf you omit the --platform flag, Docker may attempt to guess the platform based on the first entry in the manifest or the host's default behavior, which can lead to exec format error if the guess is wrong. Explicitly defining it guarantees that the correct binary is executed.
Troubleshooting Common Errors
- Exec Format Error: This usually means you tried to run an ARM binary on an AMD64 host (or vice versa) without the platform flag. Always verify your host architecture using
uname -m. - Image Not Found: Ensure the image was successfully loaded before trying to run it. Check
docker imagesto confirm presence. - Manifest Mismatch: If the tarball was corrupted or created with incompatible tooling, the manifest might be unreadable. Re-export the image from a clean source.
Best Practices for Deployment
When automating deployments, always include the --platform flag in your scripts or CI/CD pipelines. This makes your builds deterministic regardless of where they are executed. Additionally, consider tagging your images with the architecture in the name, such as myimage-amd64:latest, to reduce ambiguity for team members.
For environments where you manage many containers, understanding the underlying ID structure can help with debugging. See Understanding the ID of Docker (999) to learn more about how Docker identifies and manages internal object references.
Frequently Asked Questions
Can I extract only one architecture from a multi-arch tarball?
No, the docker load command imports the entire manifest and all associated layers. You cannot selectively load just one architecture from a multi-arch tarball directly. You must load the whole image and then choose the platform at runtime.
What happens if I don't specify the platform flag?
Docker will attempt to select the default platform based on the manifest order or the host's native architecture. If the selected variant is incompatible with your hardware, the container will fail to start with an exec format error.
Does docker save preserve multi-arch manifests?
Yes, the standard docker save command preserves the multi-architecture manifest list. This allows the receiving machine to inspect all available architectures and choose the appropriate one when running the container.
How do I check my host's current architecture?
You can determine your host's architecture by running the command uname -m in the terminal. Common outputs include x86_64 for AMD64 and aarch64 for ARM64.
Is there a performance penalty for using the platform flag?
No, there is no performance penalty. The --platform flag only influences the selection of the image variant during startup. Once the correct binary is loaded into memory, execution speed is identical to a natively built image.