How to Enable and Use Rosetta for x86_64 Binaries in ARM Containers

To run x86-64 containers on Apple Silicon, pass the --rosetta flag alongside --arch amd64 when executing container run or container build, or permanently enable translation by setting rosetta = true in the [build] and [container] sections of ~/.config/container/config.toml.

The apple/container project executes workloads inside a lightweight Linux VM. When operating on ARM64 hosts (Apple Silicon), running AMD64 (x86-64) binaries requires Apple Rosetta 2 for instruction translation. Because Rosetta adds computational overhead, the feature is disabled by default and must be explicitly opted into via CLI flags or configuration files.

Runtime Translation with Rosetta

Activating Rosetta via CLI Flags

The --rosetta flag explicitly enables the translation layer for the container or build VM, as documented in docs/command-reference.md (lines 70-71). To enable Rosetta for a specific execution, combine this flag with --arch amd64 (or --platform linux/amd64):

container run --arch amd64 --rosetta --rm ghcr.io/apple/containerbuilder/example:latest uname -a

As demonstrated in docs/how-to.md (lines 81-86), this command outputs an x86_64 kernel string even on Apple Silicon hardware, confirming that Rosetta 2 is translating x86-64 instructions in real-time.

Architecture Detection and Injection Logic

Under the hood, the client automatically validates compatibility before launching. In Sources/Services/ContainerAPIService/Client/Utility.swift (lines 239-242), the system checks if the host architecture is arm64 and the requested platform is amd64. When this mismatch is detected, the code automatically sets the rosetta flag internally (or throws an error if translation is not permitted), ensuring seamless cross-architecture execution without manual intervention.

Build-Time Rosetta Configuration

Builder VM Settings

When building images that target x86-64, the builder VM must also have Rosetta enabled. The build process respects the --rosetta CLI option or the build.rosetta configuration key. According to the implementation in Sources/Services/RuntimeLinux/Server/RuntimeService.swift (line 168), the builder VM is launched with the rosetta parameter derived from the active configuration.

Multi-Architecture Builds

For multi-platform images, enable Rosetta when specifying multiple architectures:

container build \
    --arch arm64 \
    --arch amd64 \
    --rosetta \
    -t myrepo/multiarch:latest \
    .

In this scenario, the builder VM uses Rosetta to handle x86-64 instruction translation while producing the AMD64 layer, while the ARM64 layer compiles natively.

Persistent Configuration

Global TOML Settings

Rather than passing flags for every command, persist the setting in ~/.config/container/config.toml. The ContainerSystemConfig struct, defined in Sources/ContainerPersistence/ContainerSystemConfig.swift, loads these values at startup and exposes them through ContainerSystemConfig properties.

Create or edit the configuration file:

cat <<EOF > ~/.config/container/config.toml
[build]
rosetta = true   # Builder VM always uses Rosetta for non-native architectures

[container]
rosetta = true   # Runtime containers automatically enable Rosetta

EOF

When build.rosetta is true, the builder VM automatically enables translation for AMD64 targets. Similarly, container.rosetta controls whether runtime containers use Rosetta by default, as defined in Sources/ContainerResource/Container/ContainerConfiguration.swift.

Verifying Configuration

To confirm the settings are active, query the system properties:

container system property list | grep rosetta

Expected output shows both flags enabled:

rosetta = true

Summary

• Rosetta is disabled by default in apple/container to minimize performance overhead on ARM hosts.
• Use --rosetta --arch amd64 to enable translation for specific container run or container build commands.
• Set rosetta = true in both [build] and [container] sections of ~/.config/container/config.toml to enable it permanently.
• Multi-architecture builds require the --rosetta flag when including amd64 targets on Apple Silicon.
• Architecture validation occurs automatically in Utility.swift, which injects the Rosetta flag when detecting an arm64 host running amd64 binaries.

Frequently Asked Questions

Do I need Rosetta enabled to run x86-64 containers on Apple Silicon?

Yes. Without the --rosetta flag or persistent configuration enabled, attempting to run an AMD64 container on an ARM64 host will fail. The container tool requires explicit opt-in because Rosetta translation adds computational overhead that is unnecessary for native ARM64 workloads.

Where does the container CLI store the default Rosetta setting?

The default settings are stored in ~/.config/container/config.toml. The ContainerSystemConfig class, implemented in Sources/ContainerPersistence/ContainerSystemConfig.swift, reads the [build] and [container] sections at startup, applying the rosetta boolean to both builder VMs and runtime containers respectively.

Can I use Rosetta for multi-architecture image builds?

Yes. When building multi-arch images that include amd64 alongside arm64, pass the --rosetta flag. The builder VM, configured via RuntimeService.swift (line 168), uses Rosetta to translate x86-64 instructions while constructing the AMD64 image layer, allowing simultaneous native ARM64 builds and translated x86-64 builds on the same host.

Is there a performance penalty when using Rosetta 2?

Yes. Rosetta 2 translates x86-64 instructions to ARM64 on the fly, which introduces overhead compared to native execution. This is why apple/container disables it by default and requires explicit activation via the --rosetta flag or configuration file.

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