Help Center/ SoftWare Repository for Container/ Best Practices/ Creating Multi-Architecture Images
Updated on 2025-09-10 GMT+08:00

Creating Multi-Architecture Images

Scenarios

When images are required in the x86 and Arm architectures, and different image tags need to be set, you can create multi-architecture images and manage these images of the same tag using the docker manifest command.

Preparations

  1. Check the Docker version.

    Ensure that you use Docker 19.03 or later that supports the manifest extension. Run the following command to view the version:

    docker --version
  2. If your Docker version is earlier than 19.03, set the experimental environment variable.
    Open the Docker daemon configuration file /etc/docker/daemon.json.
    vim /etc/docker/daemon.json

    Change the value of experimental to true. If this field does not exist, add it.

      "experimental": true

    Save the file and restart Docker to apply the modification.

    sudo systemctl restart docker
  3. Check whether experimental Docker CLI features are enabled.
    echo $DOCKER_CLI_EXPERIMENTAL

    • If enabled is returned, experimental Docker CLI features are enabled.
    • If disabled or no information is returned, experimental Docker CLI features are not enabled.

Procedure

  1. Build and push two images to the image repository by following the instructions in Creating a JDK8 Base Image and Pushing It to SWR.

    docker push ${repository_url}/${organization}/${image_name}:${image_tag}-amd64
    docker push ${repository_url}/${organization}/${image_name}:${image_tag}-arm64

  2. Build a manifest for the multi-architecture images.

    1. Create a manifest.
      docker manifest create --amend --insecure ${repository_url}/${organization}/${image_name}:${image_tag} ${repository_url}/${organization}/${image_name}:${image_tag}-amd64 ${repository_url}/${organization}/${image_name}:${image_tag}-arm64
    1. Modify the manifest to add arch information.
      docker manifest annotate ${repository_url}/${organization}/${image_name}:${image_tag} ${repository_url}/${organization}/${image_name}:${image_tag}-amd64 --arch amd64
      docker manifest annotate ${repository_url}/${organization}/${image_name}:${image_tag} ${repository_url}/${organization}/${image_name}:${image_tag}-arm64 --arch arm64

  3. Push the manifest.

    docker manifest push ${repository_url}/${organization}/${image_name}:${image_tag}

Downloading an Image Across CPU Architectures

Use the --platform parameter to specify the architecture of the image to be pulled.

docker pull ${repository_url}/${organization}/${image_name}:${image_tag} --platform=linux/amd64

--platform parameter description:

  • --platform=linux/amd64: Linux system of the x86_64 architecture
  • --platform=linux/arm64: Linux system of the ARM64 architecture