How to Use Rosetta Translation Within arm64 Containers on macOS

Apple Silicon Macs can execute x86-64 binaries inside arm64 containers by enabling Rosetta 2 translation through the --rosetta flag or the rosetta configuration property in ~/.config/container/config.toml.

The container CLI from the apple/container repository enables Apple Silicon users to run Intel-compatible workloads within arm64 containers without rebuilding images for multiple architectures. This capability leverages Rosetta 2 translation to seamlessly execute amd64 binaries in a lightweight builder VM.

How Rosetta Translation Works

When you execute container run or container build, the runtime creates a lightweight builder VM for each operation. According to the source code in docs/how-to.md, enabling Rosetta causes the VM to utilize the qemu-aarch64 binary alongside the Rosetta translation layer. This combination allows x86-64 instructions to execute transparently on Apple Silicon hardware.

The translation occurs automatically when:

• The container architecture is arm64 (native)
• The binary architecture is amd64 (x86-64)
• Rosetta is enabled in the configuration or via CLI flag

When active, an amd64 binary such as uname reports an x86-64 environment, while native arm64 binaries show the underlying aarch64 architecture.

Configuring Rosetta Translation

The container CLI provides two methods to control Rosetta translation behavior: per-command flags and global configuration files.

Per-Command Configuration

Use the --rosetta flag with container run or container create to override the global setting for a specific invocation. This flag forces the builder VM to use Rosetta for any non-native architecture.

# Explicitly enable Rosetta for a single run

container run --rosetta --arch amd64 --rm myregistry/example:latest uname -a

# Disable Rosetta for a single run (forces native arm64 execution)

container run --no-rosetta --arch amd64 --rm myregistry/example:latest uname -a

When you specify --no-rosetta, the command fails if the binary lacks arm64 compatibility, as the system attempts native execution without translation.

Global Configuration

Set the default behavior for all container operations by editing ~/.config/container/config.toml. As documented in docs/container-system-config.md, the rosetta property under the [build] section controls global defaults.

# Disable Rosetta globally

cat > ~/.config/container/config.toml <<EOF
[build]
rosetta = false
EOF

The default value is true, meaning Rosetta translation is enabled by default on fresh installations. Changes to this file affect subsequent container run and container build commands unless overridden by the --rosetta CLI flag.

Verifying Rosetta Translation

Confirm that Rosetta is active by checking the architecture reported within the container. The docs/how-to.md file demonstrates this verification technique using the uname command.

Run an amd64 binary with Rosetta enabled:

container run --arch amd64 --rm myregistry/example:latest uname -a

# Output: Linux <id> … x86_64 GNU/Linux

Compare with a native arm64 execution:

container run --arch arm64 --rm myregistry/example:latest uname -a

# Output: Linux <id> … aarch64 GNU/Linux

When the amd64 container reports x86_64 while running on Apple Silicon, Rosetta translation is confirmed active.

Configuration Reference

The following documentation files in the apple/container repository define Rosetta behavior:

• docs/how-to.md: Demonstrates Rosetta behavior with practical uname examples and explains the translation mechanism
• docs/container-system-config.md: Lists the rosetta configuration property and documents its default value of true
• docs/command-reference.md: Documents the --rosetta and --no-rosetta CLI flags for container run and container create commands

Summary

• Rosetta is enabled by default (rosetta = true) in ~/.config/container/config.toml
• Use the --rosetta flag to force translation for a specific command, or --no-rosetta to disable it
• Global configuration changes apply to all future builds until modified or overridden by CLI flags
• Verify translation is active by running uname -a in an amd64 container and checking for x86_64 output
• The builder VM leverages qemu-aarch64 with the Rosetta layer to execute x86-64 binaries on Apple Silicon

Frequently Asked Questions

How do I disable Rosetta translation permanently?

Edit ~/.config/container/config.toml and set rosetta = false under the [build] section. This global setting persists across all future container run and container build commands until you change the configuration file again or override it with the --rosetta flag.

Can I mix arm64 and x86-64 binaries in the same container?

Yes. When Rosetta is enabled, the builder VM can execute both native arm64 binaries and translated x86-64 binaries within the same container instance. The system automatically routes amd64 binaries through the Rosetta translation layer while allowing arm64 binaries to run natively.

What happens if I run an x86-64 container without Rosetta?

If you attempt to run an amd64 container with --no-rosetta (or with rosetta = false globally), the command fails with an execution error. The container runtime cannot execute x86-64 instructions on Apple Silicon hardware without the Rosetta translation layer or explicit multi-architecture support in the image.

Does Rosetta translation affect container performance?

Rosetta translation introduces minimal overhead for most workloads, but CPU-intensive x86-64 binaries may run slower than their native arm64 equivalents. For production workloads, building native arm64 images eliminates translation overhead entirely while maintaining compatibility with Apple Silicon Macs.

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