# Does apple/container Support Multi-Arch and Multi-Platform Image Builds?

> Yes apple/container supports multi-arch and multi-platform image builds using --arch and --platform CLI flags. Learn how to build universal containers easily.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-22

---

**Yes, apple/container fully supports building and publishing multi-architecture and multi-platform container images through its `--arch` and `--platform` CLI flags.**

The **apple/container** repository provides native tooling for creating container images that target multiple CPU architectures and operating systems in a single workflow. This capability aligns with OCI image specifications and matches the multi-platform features found in Docker BuildKit.

## Building Multi-Architecture Images with the `--arch` Flag

The CLI accepts the `--arch` flag multiple times within a single `container build` command. This allows developers to produce a single image containing variants for each specified architecture without requiring separate build processes.

According to the documentation in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 63-71), you can specify multiple architectures to build **arm64** and **amd64** variants simultaneously:

```bash
container build \
    --arch arm64 \
    --arch amd64 \
    --tag registry.example.com/fido/web-test:latest \
    --file Dockerfile .

```

The `--arch` flag can be repeated to add any number of architectures supported by the host, including less common targets like `riscv64`.

## Automatic Multi-Platform Manifest Generation

When pushing multi-architecture images to a registry, **apple/container** automatically creates the multi-platform manifest without requiring additional flags. As documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 89-93), the standard push command handles the manifest list creation:

```bash
container image push registry.example.com/fido/web-test:latest

```

This behavior mirrors the OCI image index specification, ensuring that container runtimes can automatically select the appropriate architecture variant when pulling the image.

## Selecting Specific Platforms at Runtime

For commands that need to target a specific variant—such as `run`, `pull`, `push`, or `save`—the CLI provides a `--platform` option that accepts an `<os/arch[/variant]>` string. This overrides the separate `--os` and `--arch` flags and is documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 66-71).

You can run a specific architecture variant using either the `--arch` shorthand or the full `--platform` specification:

```bash

# Using --arch flag

container run --arch arm64 --rm registry.example.com/fido/web-test:latest uname -a

# → Linux … aarch64 GNU/Linux

container run --arch amd64 --rm registry.example.com/fido/web-test:latest uname -a

# → Linux … x86_64 GNU/Linux

# Using --platform flag

container run --platform linux/arm64 --rm registry.example.com/fido/web-test:latest

```

## Internal Implementation of Platform Selection

The internal `Flags` structure in [`Sources/Services/MachineAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/MachineAPIService/Client/Flags.swift) (lines 30-32) defines a `platform` option that takes precedence over individual `--os` and `--arch` flags. This implementation ensures consistent platform resolution across all CLI commands that support platform targeting.

The code structure validates the platform string according to OCI standards before passing it to the underlying container runtime, ensuring compatibility with multi-platform registry operations.

## Summary

- **apple/container** supports multi-arch builds by accepting repeated `--arch` flags in the `build` command
- Multi-platform manifests are generated automatically when pushing images to registries
- The `--platform` flag provides granular control for selecting specific OS/architecture combinations during `run`, `pull`, and `push` operations
- Internal flag parsing in [`Flags.swift`](https://github.com/apple/container/blob/main/Flags.swift) prioritizes the platform string over separate OS and architecture parameters
- The implementation follows OCI image specifications and supports standard container registry workflows

## Frequently Asked Questions

### Can I build for more than two architectures simultaneously?

Yes. The `--arch` flag can be repeated any number of times to include additional architectures such as `riscv64`, `ppc64le`, or `s390x`, provided the host system supports building for those targets. Each architecture specified generates a separate variant within the final image manifest.

### Do I need special flags to push multi-platform images?

No. The standard `container image push` command automatically detects multi-architecture images and creates the appropriate manifest list. As noted in the how-to documentation, no extra flags are required beyond the standard registry URL and tag.

### How do I select a specific OS/architecture combination when running a container?

Use the `--platform` flag followed by the OS/architecture string (e.g., `--platform linux/arm64` or `--platform linux/amd64`). Alternatively, use `--arch` for architecture-only selection. The `--platform` option takes precedence and is parsed by the `Flags` structure in [`Sources/Services/MachineAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/MachineAPIService/Client/Flags.swift).

### Does apple/container support platform variants like arm/v7?

Yes. The `--platform` flag accepts the full OCI platform specification format `os/arch/variant`, allowing you to target specific variants such as `linux/arm/v7` or `linux/arm64/v8`. This is handled by the platform parsing logic implemented in the CLI's flag validation system.