How to Use Rosetta for x86_64 Binary Translation in Apple Container

The container CLI enables Rosetta 2 by default for x86_64 binary translation on Apple silicon, allowing you to run and build amd64 Linux containers natively through the --rosetta flag or the rosetta configuration key in ~/.config/container/config.toml.

The apple/container tool runs Linux VMs on macOS using Apple silicon hypervisor features. When you need to execute Intel architecture (amd64) containers on an Apple silicon Mac, the tool leverages Rosetta 2 for x86_64 binary translation instead of slower QEMU emulation.

How Rosetta Configuration Works

The container tool checks three sources to determine whether to enable Rosetta for x86_64 binary translation. By default, Rosetta is enabled (true) in all locations.

The configuration sources, in order of precedence, are:

• CLI flag: --rosetta defined in Sources/Services/ContainerAPIService/Client/Flags.swift at line 325
• System configuration: The rosetta key in Sources/ContainerPersistence/ContainerSystemConfig.swift at line 81
• User configuration file: The rosetta key under [build] in ~/.config/container/config.toml

When enabled, the builder VM automatically starts Rosetta. Any amd64 binaries execute under translation, reporting an x86_64 environment. When disabled, the VM runs without Rosetta, causing amd64 binaries to fail because Apple silicon hardware cannot execute them natively.

The Translation Pipeline

Understanding the internal flow helps debug architecture-related issues. The process follows four distinct stages:

1. CLI parsing: The --rosetta flag is added to the command line by Flags.swift and stored in the ContainerCommand options.
2. System configuration: ContainerSystemConfig.swift reads the rosetta key (or falls back to the default) and propagates the value to the builder.
3. Builder initialization: In Sources/ContainerCommands/Builder/BuilderStart.swift, the code checks containerSystemConfig.build.rosetta. If true, it omits the --enable-qemu argument and sets config.rosetta = true so the VM launches with Rosetta support.
4. Container execution: When you specify --arch amd64, the container run command launches the VM with Rosetta active; the guest sees an x86_64 kernel and can execute any x86-64 binary.

Running x86_64 Containers with Rosetta

By default, Rosetta handles x86_64 binary translation seamlessly. You can verify this by running an amd64 container and checking the reported architecture.

Build a multi-architecture image first:

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

Then run the amd64 variant to see Rosetta translation in action:

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

According to the documentation 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 and Using QEMU

You may need to disable Rosetta for debugging or to force pure emulation. When Rosetta is disabled, the builder falls back to QEMU by adding the --enable-qemu argument (as seen in BuilderStart.swift around line 200).

To disable Rosetta persistently, create or edit ~/.config/container/config.toml:

[build]
rosetta = false

Now when you build for amd64, the tool uses QEMU instead of Rosetta:

container build --arch amd64 --tag test:latest --file Dockerfile .

To disable Rosetta for a single command without modifying your config file, use the CLI flag:

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

Summary

• Rosetta is enabled by default (true) in container, configured via CLI flags, system defaults, or ~/.config/container/config.toml.
• Three configuration layers control the behavior: Flags.swift (CLI), ContainerSystemConfig.swift (system defaults), and your local TOML file.
• Automatic translation occurs when running amd64 containers on Apple silicon, with the guest kernel reporting x86_64 architecture.
• QEMU fallback happens when you set rosetta = false, triggering the --enable-qemu path in BuilderStart.swift instead of Rosetta.

Frequently Asked Questions

Is Rosetta for x86_64 binary translation enabled by default?

Yes. According to Sources/ContainerPersistence/ContainerSystemConfig.swift at line 81 and Sources/Services/ContainerAPIService/Client/Flags.swift at line 325, the default value for the rosetta setting is true. This means amd64 containers run under Rosetta translation immediately without configuration.

How do I completely disable Rosetta for all builds?

Add rosetta = false under the [build] section in ~/.config/container/config.toml. As implemented in Sources/ContainerCommands/Builder/BuilderStart.swift, this forces the builder to add the --enable-qemu argument instead of initializing Rosetta, causing all x86_64 binary translation to use QEMU emulation.

What happens if I run an amd64 container without Rosetta?

If Rosetta is disabled and you attempt to run an amd64 container on Apple silicon, the binary will fail to start. Unlike ARM64 binaries, x86_64 binaries cannot execute natively on Apple silicon hardware. The tool either uses Rosetta for efficient translation or QEMU for emulation, but without either enabled, the execution fails.

Can I toggle Rosetta for a single command without editing the config file?

Yes. Use the --rosetta CLI flag defined in Flags.swift to override the configuration for a specific invocation. For example, container run --rosetta=false --arch amd64 ... disables Rosetta just for that run, while container run --rosetta ... explicitly ensures it is enabled.

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