# How to Enable Rosetta for x86_64 Emulation in Containers: A Complete Guide

> Enable Rosetta for x86_64 emulation in containers on Apple Silicon. Learn how to configure `.config/container/config.toml` or use CLI flags for seamless binary translation. Get the complete guide now.

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

---

**Set `rosetta = true` under `[build]` in `~/.config/container/config.toml`, pass the `--rosetta` CLI flag, or set `config.rosetta = true` in Swift to enable x86_64 binary translation on Apple Silicon hosts.**

The `apple/container` framework supports running x86_64 Linux binaries on Apple Silicon Macs by leveraging Rosetta 2 translation technology. This capability is gated through a Boolean `rosetta` property that propagates through multiple layers of the system, from configuration files to the runtime VM. Understanding how to enable Rosetta allows you to run legacy x86_64 container images natively on arm64 hardware.

## Understanding the Rosetta Configuration Architecture

The Container framework implements Rosetta support through a layered configuration system that validates the host architecture before enabling translation.

### Configuration Model Layer

At the core of the system, `ContainerConfiguration` defines the `rosetta` property as a Boolean value defaulting to `false`. When this flag is set to `true`, the container runtime instructs the VM to start Rosetta translation for x86_64 binaries.

This property is defined in [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift).

### System-Wide Defaults

For persistent configuration, `ContainerSystemConfig` reads the `[build] rosetta` value from the user's [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file located at `~/.config/container/config.toml`. If the value is omitted, the system falls back to `Self.defaultRosetta`.

This persistence layer is implemented in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift).

### Runtime Propagation

When a build or run request reaches the builder VM, the `RuntimeService` receives the `rosetta` flag and starts the VM with Rosetta translation enabled. This final integration point ensures that the configuration actually reaches the virtualization layer.

The runtime implementation resides in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift).

## Methods to Enable Rosetta for x86_64 Emulation

You can enable Rosetta through three interfaces depending on whether you need persistent, per-command, or programmatic control.

### Configuration File (Persistent)

Add the following to your Container configuration file to enable Rosetta for all subsequent container operations:

```toml
[build]
rosetta = true

```

Save this to `~/.config/container/config.toml`. After saving, any subsequent `container build` or `container run` commands will automatically start the builder VM with Rosetta translation enabled.

### CLI Flag (Per-Invocation)

Use the `--rosetta` flag when running specific commands to override the configuration file for a single invocation:

```bash
container run --rosetta --name my-x86-app alpine:latest /bin/sh -c "echo Hello from x86_64"

```

The `--rosetta` flag is documented in [`Docs/command-reference.md`](https://github.com/apple/container/blob/main/Docs/command-reference.md) and is scoped only to the current command; it does not modify your global configuration.

### Programmatic API (Swift)

For custom tooling or applications built on the Container framework, enable Rosetta directly on the configuration object:

```swift
import ContainerResource

var cfg = try ContainerConfiguration(
    id: "my-container",
    image: ImageDescription(name: "alpine", tag: "latest"),
    process: ProcessConfiguration(command: ["/bin/sh"])
)
cfg.rosetta = true      // Enable Rosetta for this container

```

Passing this configuration to the Container API will launch the container with x86_64 emulation enabled. The client validates the host architecture before sending the request.

## Host Architecture Validation

Rosetta can only be enabled on arm64 hosts (Apple Silicon). The client validates this requirement and throws a `ContainerizationError` if a non-arm64 host attempts to enable Rosetta.

This validation logic is located in [`Sources/Services/ContainerAPIService/Client/Utility.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Utility.swift). Attempting to enable Rosetta on Intel Macs will result in an immediate error before the container starts.

## Summary

- **Configuration property**: The `rosetta` Boolean in `ContainerConfiguration` controls x86_64 emulation, defaulting to `false` in [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift).
- **Persistence**: Set `rosetta = true` under `[build]` in `~/.config/container/config.toml` for global defaults handled by `ContainerSystemConfig`.
- **CLI override**: Use the `--rosetta` flag for per-command execution as documented in [`Docs/command-reference.md`](https://github.com/apple/container/blob/main/Docs/command-reference.md).
- **Architecture restriction**: Rosetta requires an arm64 host; validation occurs in [`Sources/Services/ContainerAPIService/Client/Utility.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Utility.swift).
- **Runtime activation**: The `RuntimeService` receives the flag and enables translation at VM startup in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift).

## Frequently Asked Questions

### Can I enable Rosetta on Intel Macs?

No. Rosetta is only available on Apple Silicon (arm64) hosts. The Container framework explicitly validates the host architecture in [`Sources/Services/ContainerAPIService/Client/Utility.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Utility.swift) and throws a `ContainerizationError` if you attempt to enable Rosetta on non-arm64 hardware.

### Does the `--rosetta` CLI flag modify my global configuration?

No. The `--rosetta` flag affects only the current command invocation. According to the command reference in [`Docs/command-reference.md`](https://github.com/apple/container/blob/main/Docs/command-reference.md), this flag sets `config.rosetta` temporarily and does not write to `~/.config/container/config.toml`. For persistent settings, modify the TOML configuration file directly.

### Where is the default Rosetta setting stored?

The default Rosetta setting is managed by `ContainerSystemConfig` in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift). The system reads from `[build] rosetta` in the user's [`config.toml`](https://github.com/apple/container/blob/main/config.toml), falling back to `Self.defaultRosetta` if the key is absent. The configuration file follows the XDG standard and resides at `~/.config/container/config.toml`.

### Can I enable Rosetta for specific containers but not others?

Yes. Use the programmatic Swift API to set `config.rosetta = true` only on specific `ContainerConfiguration` instances, or use the `--rosetta` CLI flag for individual commands. The configuration file method applies globally to all builds and runs, while the API and CLI methods give you granular control per container.