# How to Enable and Use Rosetta for x86_64 Binary Translation in Apple Container

> Learn how to enable and use Rosetta for x86_64 binary translation in Apple containers. Run amd64 containers seamlessly on Apple Silicon Macs with native translation.

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

---

**The Apple `container` tool enables Rosetta 2 by default for x86_64 binary translation on Apple Silicon Macs, allowing seamless execution of `--arch amd64` containers through native translation rather than QEMU emulation.**

The `container` repository provides a Linux container runtime for macOS that leverages the Apple Silicon hypervisor framework. When running x86_64 (amd64) container images on Apple Silicon hardware, the tool utilizes Rosetta 2 to translate binaries at near-native speed, bypassing the performance overhead of traditional emulation.

## How Rosetta Integration Works

When you execute a command targeting the `amd64` architecture, `container` orchestrates a Linux VM that automatically loads Rosetta 2 for binary translation. According to the source code in [`Sources/ContainerCommands/Builder/BuilderStart.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderStart.swift), the system checks the `containerSystemConfig.build.rosetta` setting before launching the builder. If **enabled**, the VM omits the `--enable-qemu` argument and initializes with Rosetta support active, allowing the guest kernel to execute x86_64 instructions directly through translation.

### Configuration Hierarchy

The `rosetta` setting propagates through three layers:

1. **CLI Flag**: Parsed in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) (line 325) via the `--rosetta` argument
2. **System Config**: Read from `~/.config/container/config.toml` by [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) (line 81)
3. **Default Value**: Hardcoded to `true` in both locations, ensuring Rosetta is active unless explicitly disabled

## Enabling Rosetta for x86_64 Containers

By default, Rosetta is enabled for all builds and runs. You can verify or override this behavior through the CLI or configuration file.

### Using the Command-Line Flag

The `--rosetta` flag defined in [`Flags.swift`](https://github.com/apple/container/blob/main/Flags.swift) allows you to explicitly control translation for individual commands:

```bash

# Force Rosetta on for a specific run

container run --arch amd64 --rosetta --rm myimage:latest uname -m

```

### Configuring via config.toml

For persistent settings, modify `~/.config/container/config.toml` as documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md):

```toml
[build]
rosetta = true

```

This TOML key is parsed by [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) and passed to the builder logic in [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift).

## Running x86_64 Containers with Rosetta

To execute an amd64 container image under Rosetta translation, specify the architecture and run the container. The VM automatically handles the translation layer.

### Building Multi-Architecture Images

First, build an image supporting both arm64 and amd64:

```bash
container build \
  --arch arm64 \
  --arch amd64 \
  --tag localhost:5000/web-test:latest \
  --file Dockerfile .

```

### Executing x86-64 Binaries

Run the amd64 variant to trigger Rosetta translation:

```bash
container run --arch amd64 --rm localhost:5000/web-test:latest uname -a

```

As documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 81–86), the output confirms the x86_64 environment:

```

Linux c0376e0a-0bfd-4eea-9e9e-9f9a2c327051 6.1.68 #1 SMP Mon Mar 31 18:27:51 UTC 2025 x86_64 GNU/Linux

```

## Disabling Rosetta for QEMU Debugging

To force QEMU emulation instead of Rosetta (useful for debugging or testing pure emulation performance), disable the setting in your configuration file:

```toml

# ~/.config/container/config.toml

[build]
rosetta = false

```

When `rosetta` is set to `false`, [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift) (around line 200) automatically appends `--enable-qemu` to the VM startup arguments, switching from Rosetta translation to QEMU emulation for x86_64 binaries.

## Summary

- **Rosetta is enabled by default** (`true`) in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) and [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift)
- **Configuration** persists in `~/.config/container/config.toml` under the `[build]` section
- **CLI override** is available via the `--rosetta` flag for per-command control
- **Builder logic** in [`Sources/ContainerCommands/Builder/BuilderStart.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderStart.swift) selects Rosetta or QEMU based on the boolean value
- **Execution** of `container run --arch amd64` automatically utilizes the translation layer when enabled

## Frequently Asked Questions

### Is Rosetta enabled by default in container?

Yes. According to [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) (line 81) and [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) (line 325), the default value for the `rosetta` setting is `true`. This means x86_64 containers automatically run under Rosetta 2 translation on Apple Silicon unless you explicitly disable it.

### How do I disable Rosetta for a specific build?

Set `rosetta = false` under the `[build]` section in `~/.config/container/config.toml`. When disabled, [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift) automatically injects `--enable-qemu` into the VM startup parameters, forcing the use of QEMU emulation instead of Rosetta translation for that architecture.

### Can I use Rosetta for container run operations or only builds?

Rosetta works for both building and running containers. When you execute `container run --arch amd64` with Rosetta enabled, the VM launches with the translation layer active, allowing the x86_64 kernel and user-space binaries to execute natively through Rosetta 2 as described in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md).

### What happens if I try to run an amd64 container without Rosetta?

Without Rosetta enabled and without QEMU fallback, the container will fail to start because Apple Silicon CPUs cannot natively execute x86_64 instructions. The tool prevents this failure by defaulting to Rosetta (`true`), but if you explicitly disable it without enabling QEMU, the binary execution will error out due to architecture mismatch.