# How Rosetta Translation Works for amd64 Images on arm64 Hosts in Apple Container

> Explore how Rosetta translation enables amd64 image execution on arm64 Apple Silicon hosts. Learn about the lightweight VM and Rosetta 2 support that replaces QEMU emulation.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: internals
- Published: 2026-07-04

---

**Rosetta translation automatically enables x86_64 binary execution on Apple Silicon by setting `config.rosetta = true` when the host architecture is arm64 and the image architecture is amd64, launching a lightweight VM with Rosetta 2 support instead of QEMU emulation.**

The `container` tool runs Linux containers on macOS Apple Silicon by launching a lightweight virtual machine that hosts the container process. When the host CPU architecture is **arm64** but the container image declares **amd64**, the system automatically enables macOS Rosetta 2 translation for the VM. This allows amd64 binaries to execute natively without manual configuration.

## Architecture Detection and Automatic Enablement

The translation flow relies on automatic platform detection at multiple layers of the stack. When you request an amd64 image on an arm64 Mac, the system evaluates the architecture mismatch and configures Rosetta accordingly.

### Machine Creation Logic

During container-machine instantiation, the service inspects the requested platform and host architecture. In [`Sources/Services/MachineAPIService/Server/MachinesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/MachineAPIService/Server/MachinesService.swift), the configuration is set automatically:

```swift
config.rosetta = platform.architecture == "amd64" && Arch.hostArchitecture() == .arm64

```

This single line enables Rosetta translation specifically when the image architecture is amd64 and the host is Apple Silicon. The boolean assignment eliminates the need for users to manually specify translation support for standard cross-architecture runs.

### Container Configuration Utility

During launch, the utility that builds the final `ContainerConfiguration` performs an additional validation. In [`Sources/Services/ContainerAPIService/Client/Utility.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Utility.swift), the logic merges user preferences with automatic detection:

```swift
config.rosetta = management.rosetta ||
                 (Platform.current.architecture == "arm64" && requestedPlatform.architecture == "amd64")

```

This guarantees Rosetta is enabled for any container process that requires it, regardless of whether the user supplied the `--rosetta` flag explicitly. The dual-check ensures robust coverage across different invocation paths.

## Builder Shim and QEMU Fallback

The image builder VM respects the same Rosetta flag, determining whether to use native translation or fall back to QEMU emulation.

### Conditional QEMU Flags

In [`Sources/ContainerCommands/Builder/BuilderStart.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderStart.swift), the shim arguments include `--enable-qemu` **only** when Rosetta is not requested:

```swift
let shimArguments = [
    "--debug",
    "--vsock",
    useRosetta ? nil : "--enable-qemu",
].compactMap { $0 }

```

When `useRosetta` evaluates to `true`, the code omits `--enable-qemu` from the argument array. This directs the VM to start under Rosetta translation rather than QEMU emulation, providing significantly better performance for x86_64 build processes.

## User Configuration and CLI Flags

While automatic detection handles most use cases, you can explicitly control Rosetta behavior through configuration files and command-line options.

### Command-Line Options

The `--rosetta` flag defaults to `true`, meaning amd64 images automatically run under translation on arm64 hosts. To disable Rosetta for a specific run and force QEMU emulation:

```bash
container run --arch amd64 --no-rosetta --rm ghcr.io/library/alpine:latest uname -a

```

To explicitly enable Rosetta when overriding a disabled configuration:

```bash
container run --arch amd64 --rosetta --rm ghcr.io/library/alpine:latest uname -a

```

### Configuration File Settings

The `~/.config/container/config.toml` file allows persistent configuration of Rosetta behavior. To disable Rosetta for all builds by default:

```bash
echo "[build]\nrosetta = false" > ~/.config/container/config.toml

```

This global setting affects the builder shim logic, causing `--enable-qemu` to be appended to VM arguments unless explicitly overridden at the command line.

## Practical Examples

### Running an amd64 Image with Automatic Translation

When Rosetta is enabled (the default), running an amd64 container on Apple Silicon automatically uses translation:

```bash
container run --arch amd64 --rm ghcr.io/library/alpine:latest uname -a

```

The output demonstrates successful x86_64 execution:

```

Linux c0376e0a-0bfd-4eea-9e9e-9f9a2c327051 6.1.68 #1 SMP Mon Mar 31 18:27:51 UTC 2025 x86_64 GNU/Linux

```

### Verifying Translation Mode

You can verify whether Rosetta is active by checking the architecture string inside the container. If the output shows `x86_64` while running on an arm64 host, Rosetta 2 is successfully translating the amd64 binary instructions.

## Summary

- **Automatic detection** occurs in [`MachinesService.swift`](https://github.com/apple/container/blob/main/MachinesService.swift) and [`Utility.swift`](https://github.com/apple/container/blob/main/Utility.swift), setting `config.rosetta = true` when amd64 images run on arm64 hosts.
- **Builder optimization** in [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift) omits `--enable-qemu` when Rosetta is active, avoiding QEMU overhead.
- **Default behavior** enables Rosetta automatically, requiring no user intervention for standard cross-architecture containers.
- **Manual override** is available via `--rosetta`/`--no-rosetta` flags or the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) `[build]` section.

## Frequently Asked Questions

### Does Rosetta translation require manual activation for amd64 images?

No. According to the `apple/container` source code, Rosetta translation activates automatically when the host architecture is arm64 and the container image specifies amd64. The logic in [`MachinesService.swift`](https://github.com/apple/container/blob/main/MachinesService.swift) sets `config.rosetta = true` automatically based on platform detection, making the process transparent to users.

### What is the difference between Rosetta and QEMU in the container builder?

Rosetta 2 provides native translation of x86_64 instructions to ARM64, while QEMU emulates the entire x86_64 architecture in software. The [`BuilderStart.swift`](https://github.com/apple/container/blob/main/BuilderStart.swift) implementation appends `--enable-qemu` to shim arguments only when Rosetta is disabled. Rosetta offers significantly better performance for build processes because it avoids the overhead of full-system emulation.

### Can I disable Rosetta for specific container runs?

Yes. Use the `--no-rosetta` flag at the command line to force QEMU emulation for a specific run, or set `rosetta = false` in the `[build]` section of `~/.config/container/config.toml` to disable it globally. This is useful when debugging architecture-specific issues or when you require true emulation rather than translation.