# How to Use Rosetta for x86_64 Binary Translation in Apple Container

> Learn to use Rosetta for x86_64 binary translation in Apple containers. Run and build amd64 Linux containers natively on Apple silicon with the container CLI.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) at line 325
- **System configuration**: The `rosetta` key in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Flags.swift) and stored in the `ContainerCommand` options.
2. **System configuration**: [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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:

```bash
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:

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

```

According to the documentation in [`docs/how-to.md`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/BuilderStart.swift) around line 200).

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

```toml
[build]
rosetta = false

```

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

```bash
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:

```bash
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`](https://github.com/apple/container/blob/main/Flags.swift) (CLI), [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) at line 81 and [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.