# How to Use Multi-Platform Images with `--platform`, `--os`, and `--arch` Flags in Apple Container

> Master multi-platform images in Apple Container. Learn to use --platform, --os, and --arch flags effectively for precise or default image selection. Improve your build efficiency today.

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

---

**Use `--platform` for explicit `os/arch[/variant]` selection (highest priority), combine `--os` and `--arch` when omitting `--platform`, or set `CONTAINER_DEFAULT_PLATFORM` for persistent defaults.**

The **apple/container** CLI supports multi-platform image workflows through three interrelated flags that control which operating system and architecture variant to pull, build, or run. Understanding the precedence between `--platform`, `--os`, and `--arch` ensures you target the correct image variant across different command contexts.

## Platform Flag Precedence and Resolution Logic

The CLI resolves platform selection differently depending on whether you are fetching images or running containers. The core logic resides in **[`Sources/Services/ContainerAPIService/Client/DefaultPlatform.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/DefaultPlatform.swift)**, specifically in lines **65‑68** (image-fetch precedence) and **94‑98** (container-run precedence).

### Image-Fetch Commands (pull, push, save)

For commands that transfer images between registries and local storage, the precedence flows from highest to lowest:

1. **`--platform`** – Explicit full specification (e.g., `linux/amd64`)
2. **`--os` and `--arch`** – Combined when `--platform` is omitted
3. **`CONTAINER_DEFAULT_PLATFORM`** – Environment variable fallback
4. **No platform** – Requests all available platforms

As implemented in [`DefaultPlatform.swift`](https://github.com/apple/container/blob/main/DefaultPlatform.swift) (lines 65‑68), the CLI checks for `--platform` first, then constructs a platform string from the separate flags if provided.

### Container Run Commands (run, create)

For runtime operations, the precedence shifts slightly to ensure containers can execute on the host:

1. **`--platform`** – Explicit override
2. **`CONTAINER_DEFAULT_PLATFORM`** – Environment variable
3. **Default values** – `linux` + host architecture (when no flags or env var exist)

According to lines 94‑98 of [`DefaultPlatform.swift`](https://github.com/apple/container/blob/main/DefaultPlatform.swift), the `run` and `create` commands use `resolveWithDefaults`, which falls back to the host's native architecture rather than requiring explicit flags.

## Practical Usage Examples

### Pulling Specific Platforms

Use `--platform` to extract a single variant from a multi-platform manifest:

```bash

# Pull only the linux/amd64 variant of nginx

container image pull --platform linux/amd64 nginx:latest

```

When `--platform` is present, the CLI ignores any separate `--os` or `--arch` values per the documentation in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 66).

### Using Separate OS and Architecture Flags

When you omit `--platform`, combine `--os` and `--arch` to construct the platform specification:

```bash

# Equivalent to --platform linux/arm64

container image pull --os linux --arch arm64 nginx:latest

```

The CLI concatenates these values into a platform string before validation.

### Environment Variable Defaults

Set `CONTAINER_DEFAULT_PLATFORM` to avoid repeating flags across commands:

```bash
export CONTAINER_DEFAULT_PLATFORM=linux/arm64

# Subsequent commands default to linux/arm64

container image pull nginx:latest
container run alpine:latest

```

The environment variable is consulted only after checking explicit flags, as handled by the `fromEnvironment` implementation in [`DefaultPlatform.swift`](https://github.com/apple/container/blob/main/DefaultPlatform.swift).

### Running Non-Native Platforms

Execute images built for different architectures than your host:

```bash

# Run an amd64 image on an arm64 Mac

container run --platform linux/amd64 alpine:latest uname -m

```

The `run` command validates the platform against available variants and uses emulation if necessary.

### Mixed Flag Precedence

When flags conflict, `--platform` always wins:

```bash

# Results in linux/amd64, not linux/arm64

container run --os linux --arch arm64 --platform linux/amd64 busybox

```

This behavior aligns with the precedence hierarchy documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 64‑66).

## How Platform Resolution Works in the Source Code

When executing commands, the CLI invokes `DefaultPlatform.resolve()` (for image operations) or `resolveWithDefaults()` (for container operations). The resolution flow follows this strict order:

1. **Parse `--platform`** via `ContainerizationOCI.Platform(from:)` if the flag exists
2. **Construct from parts** if `--arch` or `--os` are provided individually
3. **Check environment** using `fromEnvironment` for `CONTAINER_DEFAULT_PLATFORM`
4. **Apply defaults** (run/create only) – fallback to `linux` and host architecture

The `ContainerizationOCI.Platform` parser (located in [`Sources/ContainerizationOCI/Platform.swift`](https://github.com/apple/container/blob/main/Sources/ContainerizationOCI/Platform.swift)) validates the platform string and throws `ContainerizationError.invalidArgument` if the format is malformed, ensuring clear error messages for unsupported combinations.

## Summary

- **Use `--platform`** for explicit `os/arch[/variant]` selection; it overrides all other platform flags according to [`DefaultPlatform.swift`](https://github.com/apple/container/blob/main/DefaultPlatform.swift) lines 65‑68.
- **Combine `--os` and `--arch`** when you need to specify components separately, but remember they are ignored if `--platform` is present.
- **Set `CONTAINER_DEFAULT_PLATFORM`** for persistent defaults across sessions without typing flags repeatedly.
- **Remember the context difference**: Image-fetch commands (pull, push) require explicit platform selection or default to all platforms, while run/create commands fall back to host defaults via `resolveWithDefaults` (lines 94‑98).

## Frequently Asked Questions

### What happens if I use both `--platform` and `--arch` flags?

The `--platform` flag takes precedence and the `--arch` value is ignored. According to the precedence logic in [`DefaultPlatform.swift`](https://github.com/apple/container/blob/main/DefaultPlatform.swift), the CLI checks for `--platform` first and only evaluates separate OS/arch flags when the full platform specification is absent.

### Can I build multi-platform images using these flags?

Yes. The `container build` command accepts multiple `--platform` flags to create cross-platform images in a single invocation:

```bash
container build -t myapp:multi --platform linux/amd64 --platform linux/arm64 .

```

### Why does my container run fail with "platform not supported"?

This occurs when the requested platform (via flag or environment variable) is not present in the image manifest. Verify available platforms with `container image inspect`, or omit platform flags to let the CLI select the host-compatible variant automatically.

### How do I check which platform a container is actually using?

Inspect the container's configuration using `container inspect <container-id>` and look for the `Platform` field. If you ran the container without explicit flags, it will show the default `linux/host-arch` combination resolved by `resolveWithDefaults` in the source code.