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

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, 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 (line 325) via the --rosetta argument
2. System Config: Read from ~/.config/container/config.toml by 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 allows you to explicitly control translation for individual commands:

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

[build]
rosetta = true

This TOML key is parsed by ContainerSystemConfig.swift and passed to the builder logic in 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:

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:

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

As documented in 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:

# ~/.config/container/config.toml

[build]
rosetta = false

When rosetta is set to false, 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 and 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 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 (line 81) and 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 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.

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.

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