# How to Build and Pull Multi-Platform Images (OS/Arch Variants) with Container > Easily build and pull multi-platform container images for various OS and architectures using the --platform flag. Streamline your CI/CD with precise image variants for every target. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-10 --- **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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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: ```bash container image build \ --platform linux/amd64 \ -t myrepo/myapp:amd64 . ``` Build a Linux ARM64 image: ```bash 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: ```bash container image push myrepo/myapp:amd64 container image push myrepo/myapp:arm64 ``` Create the multi-platform manifest list: ```bash 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: ```bash 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`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) (line 307) and [`Sources/Services/MachineAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.