# How to Enable Rosetta Support in Apple Container for Running x86 Binaries

> Easily run x86 binaries on Apple Silicon Macs within containers. Learn how to enable Rosetta support using simple flags or configuration settings for seamless execution.

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

---

**Apple Silicon Macs running the `container` CLI can execute x86‑64 binaries transparently by enabling Rosetta 2 support in the underlying Linux VM, either via the `--rosetta` flag, the `--arch amd64` argument, or the `rosetta = true` setting in `~/.config/container/config.toml`.**

The `container` tool from Apple operates inside a lightweight virtual machine on Apple Silicon Macs. By default, this VM is configured to leverage Rosetta 2 for x86‑64 instruction translation, allowing seamless execution of x86 binaries within ARM‑based containers. Understanding how to control this behavior is essential for developers working with legacy architecture images or requiring native ARM builds.

## How Rosetta Works in the Container VM

When running on Apple Silicon, the `container` CLI launches a lightweight Linux VM that handles all container operations. According to the `container` source code, this VM’s *builder* is configured with `rosetta = true` by default. This setting tells the VM to start the Rosetta 2 translation layer whenever a non-native instruction set is required.

When active, the VM translates x86‑64 instructions on-the-fly using Apple’s Rosetta 2 runtime. This translation is transparent to the container’s user-space; the container sees a normal Linux environment, while the underlying VM performs the architecture conversion. Because the translation occurs at the VM level, all standard Linux tools (e.g., `apt`, `pip`, compiled binaries) work unchanged.

## Methods to Enable Rosetta Support

You can control Rosetta behavior through three distinct mechanisms, depending on whether you need a per-container override or a global default.

### Use the --rosetta CLI Flag

The most direct method is appending the `--rosetta` flag to `container run` or `container create` commands. This explicitly enables Rosetta for that specific container instance, overriding any default settings.

As documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 70), this flag forces the VM to initialize the Rosetta translation layer for the container process.

```bash
container run --rosetta --arch amd64 --rm alpine:latest uname -a

```

### Configure the Builder VM via config.toml

For persistent configuration across all operations, set `rosetta = true` under the `[build]` table in `~/.config/container/config.toml`. This controls whether the *builder* VM itself uses Rosetta for any architecture it emulates.

The property is listed in the system property documentation at [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), which defines the `rosetta` system property as a Boolean value. The configuration examples in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 81–86) demonstrate this behavior.

```bash
mkdir -p ~/.config/container
cat > ~/.config/container/config.toml <<EOF
[build]
rosetta = true         # set to false to disable

EOF

```

### Specify x86 Architecture with --arch amd64

When you run a container with `--arch amd64`, the VM automatically launches the x86‑64 version of binaries under Rosetta. The process sees an x86‑64 environment, effectively enabling Rosetta support without requiring the explicit `--rosetta` flag.

As shown in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 81–86), this method leverages the default `rosetta = true` setting in the builder to translate the foreign architecture.

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

# → Linux <id> 6.1.68 … x86_64 GNU/Linux

```

## Disabling Rosetta for Native ARM64 Builds

If you need to guarantee native arm64 images only and prevent x86 emulation, explicitly disable Rosetta by setting `rosetta = false` in your configuration file. This ensures the VM refuses to translate x86‑64 instructions and will only run native ARM binaries.

According to the *Disable Rosetta* section in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 674–681), this configuration is useful for CI pipelines or build environments that must validate pure ARM64 compatibility.

```bash
cat > ~/.config/container/config.toml <<EOF
[build]
rosetta = false
EOF

```

## Summary

- **Default behavior**: The `container` VM enables Rosetta (`rosetta = true`) by default on Apple Silicon, allowing transparent x86‑64 execution.
- **CLI override**: Use the `--rosetta` flag with `container run` or `create` for explicit per-container control.
- **Global config**: Set `rosetta = true` or `false` under `[build]` in `~/.config/container/config.toml` to control the builder VM default.
- **Architecture trigger**: Running with `--arch amd64` automatically engages Rosetta translation for x86 binaries.
- **Disable path**: Set `rosetta = false` in `~/.config/container/config.toml` to enforce native ARM64-only operation.

## Frequently Asked Questions

### Is Rosetta enabled by default in Apple Container?

Yes. The lightweight VM that powers the `container` CLI on Apple Silicon Macs starts with `rosetta = true` configured in the builder. This default setting allows immediate execution of x86‑64 binaries without manual configuration, as the VM automatically initializes the Rosetta 2 translation layer when encountering non-native architectures.

### Can I run x86 containers without Rosetta?

No. On Apple Silicon hardware, running x86‑64 (amd64) containers requires the Rosetta 2 translation layer because the underlying CPU architecture is ARM64. Without Rosetta, the VM cannot execute x86‑64 instructions. You must either enable Rosetta via the methods described above or use native ARM64 container images.

### Where is the Rosetta configuration stored?

The persistent configuration resides in `~/.config/container/config.toml` under the `[build]` table, specifically the `rosetta` boolean key. This file is created and managed by the user. Additionally, the system property is defined in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md) within the repository, which documents the VM-level behavior.

### Does Rosetta affect container performance?

Rosetta introduces a translation layer that converts x86‑64 instructions to ARM64 on-the-fly, which incurs a minor performance overhead compared to native execution. However, because Apple’s Rosetta 2 is highly optimized, most applications run with negligible latency. CPU-intensive workloads may show more noticeable differences compared to native ARM64 containers.