How to Build and Pull Multi-Platform Images (OS/Arch Variants) with Container

Use the --platform flag to specify exact OS/architecture combinations when building or pulling OCI-compatible images.

The container CLI from the apple/container repository provides native support for multi-platform images through OCI-compatible manifest lists. When you need to build and pull multi-platform images targeting specific OS and architecture variants, the --platform flag ensures you select the exact variant required for your deployment environment.

Understanding Multi-Platform Image Support

container works with OCI-compatible images that can contain manifest lists describing the same image for multiple OS/architecture combinations—such as linux/amd64, linux/arm64, or darwin/amd64. Each entry in a manifest list points to a specific platform descriptor containing the actual image layers for that architecture.

When you omit the --platform flag, container follows the manifest list's default entry—typically the first platform listed in the registry. This automatic selection works for general use cases, but explicit platform targeting ensures reproducible deployments across heterogeneous infrastructure.

The --platform Flag Implementation

The --platform flag accepts a string in the format os/arch (for example, linux/arm64) and overrides any combination of separate --os and --arch flags you might supply. This ensures the CLI targets the exact platform you request without ambiguity.

Flag Definition in Source Code

The flag is defined in the CLI's flag structs across two service layers:

• In Sources/Services/ContainerAPIService/Client/Flags.swift at line 307, the flag is defined for image-related commands such as build, pull, and push.
• In Sources/Services/MachineAPIService/Client/Flags.swift at line 30, the same definition is reused for machine-level operations.

When you pass --platform, container resolves the string to an OCI platform descriptor. For pull operations, the client requests the manifest list from the registry, selects the descriptor matching your requested platform, and downloads only that specific layer set. For build operations, the Swift Containerization package writes the platform identifier into the resulting image's configuration, enabling the CLI to include the built variant in future manifest lists.

Building Platform-Specific Images

To guarantee reproducible builds on your exact target architecture, specify the platform during the build phase. The following examples demonstrate building separate variants for AMD64 and ARM64 architectures.

Build a Linux AMD64 image:

container image build \
    --platform linux/amd64 \
    -t myrepo/myapp:amd64 .

Build a Linux ARM64 image:

container image build \
    --platform linux/arm64 \
    -t myrepo/myapp:arm64 .

Each command produces a single-architecture image tagged accordingly. The build engine encodes the platform information into the image configuration according to the OCI image specification.

Creating Multi-Platform Manifest Lists

After building individual variants, combine them under a single manifest list to distribute multi-platform images from one repository tag. This approach allows a single repository to host images for many platforms without manually juggling separate tags.

Push the individual variants:

container image push myrepo/myapp:amd64
container image push myrepo/myapp:arm64

Create the multi-platform manifest list:

container image manifest create myrepo/myapp:latest \
    --platform linux/amd64=myrepo/myapp:amd64 \
    --platform linux/arm64=myrepo/myapp:arm64

This command assembles the manifest list that points to both variants, enabling clients to automatically receive the correct image for their runtime platform.

Pulling Specific Platform Variants

To pull a specific variant explicitly rather than accepting the default manifest entry, use the --platform flag with the pull command.

Pull the ARM64 variant explicitly:

container image pull \
    --platform linux/arm64 \
    myrepo/myapp:latest

This command requests the manifest list from myrepo/myapp:latest, selects the entry matching linux/arm64, and downloads only those layers. If the requested platform is not present in the manifest list, the command returns an error indicating the platform is unavailable.

Summary

• The --platform flag in apple/container targets specific OS/architecture combinations and overrides separate --os and --arch flags.
• Flag definitions reside in Sources/Services/ContainerAPIService/Client/Flags.swift (line 307) and Sources/Services/MachineAPIService/Client/Flags.swift (line 30).
• Build operations embed the platform identifier into the image configuration using the Swift Containerization package.
• Pull operations select the appropriate descriptor from OCI manifest lists, downloading only the layers for the requested platform.
• Multi-platform distribution requires building separate variants, pushing them, and assembling them with container image manifest create.

Frequently Asked Questions

What is the difference between --platform and --os/--arch?

The --platform flag accepts a combined string like linux/arm64 and overrides any separate --os and --arch arguments you provide. According to the source code in Sources/Services/ContainerAPIService/Client/Flags.swift, using --platform ensures the CLI targets the exact platform without ambiguity, whereas separate flags might be combined in unexpected ways.

How does container select the right image when I don't specify --platform?

When you omit --platform, container requests the manifest list from the registry and selects the default entry—typically the first platform listed in the manifest. The client then downloads only the layers associated with that platform descriptor.

Can I build for multiple platforms in a single command?

No, the current implementation requires separate build commands for each platform variant. You specify --platform for each individual build, push the variants separately, and then use container image manifest create to assemble them into a multi-platform manifest list.

What OCI image formats does container support for multi-platform images?

container supports OCI-compatible images that include manifest lists (also known as multi-arch manifests or fat manifests). The tool resolves platform descriptors according to the OCI Image Specification, enabling compatibility with standard container registries that support multi-platform distribution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}