How to Enable Rosetta Translation for x86_64 Binaries in arm64 Containers

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. 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:

[build]
rosetta = false

This setting overrides the defaultRosetta value in 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, allows you to override configuration file settings for individual commands:

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, 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:

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:

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.
• 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.
• 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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}