# How to Enable Rosetta Translation for x86_64 Binaries in arm64 Containers

> Easily enable Rosetta translation for x86_64 binaries in arm64 containers with apple/container. Run amd64 images seamlessly on Apple Silicon without extra config.

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

---

**The `apple/container` tool enables Rosetta translation by default for x86_64 binaries on Apple Silicon hosts, requiring no configuration to run amd64 images, while allowing granular control via the `--rosetta` CLI flag or the `~/.config/container/config.toml` configuration file.**

The `apple/container` repository provides a container runtime that seamlessly supports x86_64 binaries on arm64 hosts through Apple's Rosetta translation technology. Understanding how to enable and configure Rosetta translation for x86_64 binaries in arm64 containers ensures optimal compatibility when running legacy Intel-based container images on Apple Silicon Macs.

## How Rosetta Translation Works by Default

Rosetta translation is automatically enabled through the `BuildConfig` struct defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). This struct contains a `rosetta` property that defaults to `true`, meaning the container runtime automatically invokes the Rosetta translation layer whenever you execute non-native x86_64 binaries on an arm64 host.

When you launch a container with the `amd64` architecture (`--arch amd64`), the builder VM detects the architecture mismatch and activates Rosetta, allowing x86_64 utilities to run at near-native speeds without manual intervention.

## Methods to Configure Rosetta Translation

You can control Rosetta behavior through three distinct configuration layers: the global user configuration file, command-line flags, or the underlying builder defaults.

### Via the Configuration File

The `~/.config/container/config.toml` file provides persistent control over Rosetta settings. To disable Rosetta globally, add the following to your configuration:

```toml
[build]
rosetta = false

```

This setting overrides the `defaultRosetta` value in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) and applies to all subsequent `container run` and `container build` commands.

### Via Command-Line Flags

The `--rosetta` flag, exposed through `Flags.Management` in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift), allows you to override configuration file settings for individual commands:

```bash
container run --rosetta --arch amd64 --rm ghcr.io/apple/container-builder-shim/builder:latest uname -a

```

Passing this flag forces the builder VM to enable Rosetta translation regardless of the configuration file setting.

### Via BuildConfig Defaults

As implemented in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), the `BuildConfig` struct initializes with `rosetta = true`. This serves as the system-wide fallback when no configuration file entry or CLI flag is present, ensuring Rosetta is available by default on Apple Silicon systems.

## Running x86_64 Containers with Rosetta Translation

To execute x86_64 binaries with Rosetta translation enabled, specify the target architecture when running your container:

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

```

When Rosetta is active, the output displays the x86_64 architecture despite running on an arm64 host:

```

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

```

The runtime automatically handles the translation flow: `CLI → Flags.Management.rosetta → ContainerSystemConfig.build.rosetta → BuilderStart`, where the builder VM initializes the Rosetta translation layer.

## Disabling and Verifying Rosetta Translation

To force pure arm64 execution without Rosetta translation, set `rosetta = false` in your `~/.config/container/config.toml` file. When disabled, the builder VM may fall back to QEMU emulation or fail to execute x86_64 binaries, depending on your specific configuration.

Verify whether Rosetta is active by checking the architecture reported inside the container:

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

```

If Rosetta is enabled, this command returns `x86_64`. If Rosetta is disabled and the container cannot execute natively, the command may return `aarch64` or fail.

## Summary

- **Rosetta is enabled by default** through `BuildConfig.defaultRosetta = true` in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift).
- **Global configuration** is controlled via the `rosetta` key in `~/.config/container/config.toml` under the `[build]` section.
- **Per-command overrides** are available through the `--rosetta` flag defined in [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift).
- **Verification** is achieved by running `uname -m` in an amd64 container and checking for `x86_64` output on an arm64 host.

## Frequently Asked Questions

### How do I check if Rosetta translation is currently enabled for my container?

Run `uname -m` inside an amd64 container using `container run --arch amd64`. If the output shows `x86_64` while running on an arm64 host, Rosetta translation is active. The `apple/container` runtime reports the translated architecture when the Rosetta layer is operational, as documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md).

### Can I disable Rosetta translation permanently?

Yes. Add `rosetta = false` to the `[build]` section of `~/.config/container/config.toml`. This overrides the default `true` value set in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift) and persists across all future container operations until changed, effectively disabling Rosetta translation for x86_64 binaries in arm64 containers.

### What happens if I run an x86_64 binary without Rosetta enabled?

If Rosetta is disabled and you attempt to run an x86_64 binary on an arm64 host, the builder VM in `apple/container` may attempt to fall back to QEMU emulation by adding `--enable-qemu` to the launch options, or the binary may fail to execute entirely depending on your specific configuration and fallback settings.

### Is the `--rosetta` flag required for every command?

No. The `--rosetta` flag is optional because the default value in `BuildConfig` is `true`. You only need to pass `--rosetta` explicitly if you have disabled it in your configuration file and want to enable it for a specific command, or if you need to ensure Rosetta translation is active when scripting container operations.