# How to Enable and Use Rosetta for x86_64 Binaries in ARM Containers

> Learn how to enable and use Rosetta for x86_64 binaries in ARM containers. Run older applications seamlessly on Apple Silicon by following our simple guide.

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

---

**To run x86-64 containers on Apple Silicon, pass the `--rosetta` flag alongside `--arch amd64` when executing `container run` or `container build`, or permanently enable translation by setting `rosetta = true` in the `[build]` and `[container]` sections of `~/.config/container/config.toml`.**

The `apple/container` project executes workloads inside a lightweight Linux VM. When operating on ARM64 hosts (Apple Silicon), running AMD64 (x86-64) binaries requires Apple Rosetta 2 for instruction translation. Because Rosetta adds computational overhead, the feature is **disabled by default** and must be explicitly opted into via CLI flags or configuration files.

## Runtime Translation with Rosetta

### Activating Rosetta via CLI Flags

The `--rosetta` flag explicitly enables the translation layer for the container or build VM, as documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 70-71). To enable Rosetta for a specific execution, combine this flag with `--arch amd64` (or `--platform linux/amd64`):

```bash
container run --arch amd64 --rosetta --rm ghcr.io/apple/containerbuilder/example:latest uname -a

```

As demonstrated in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 81-86), this command outputs an x86_64 kernel string even on Apple Silicon hardware, confirming that Rosetta 2 is translating x86-64 instructions in real-time.

### Architecture Detection and Injection Logic

Under the hood, the client automatically validates compatibility before launching. In [`Sources/Services/ContainerAPIService/Client/Utility.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Utility.swift) (lines 239-242), the system checks if the host architecture is `arm64` and the requested platform is `amd64`. When this mismatch is detected, the code automatically sets the `rosetta` flag internally (or throws an error if translation is not permitted), ensuring seamless cross-architecture execution without manual intervention.

## Build-Time Rosetta Configuration

### Builder VM Settings

When building images that target x86-64, the builder VM must also have Rosetta enabled. The build process respects the `--rosetta` CLI option or the `build.rosetta` configuration key. According to the implementation in [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) (line 168), the builder VM is launched with the `rosetta` parameter derived from the active configuration.

### Multi-Architecture Builds

For multi-platform images, enable Rosetta when specifying multiple architectures:

```bash
container build \
    --arch arm64 \
    --arch amd64 \
    --rosetta \
    -t myrepo/multiarch:latest \
    .

```

In this scenario, the builder VM uses Rosetta to handle x86-64 instruction translation while producing the AMD64 layer, while the ARM64 layer compiles natively.

## Persistent Configuration

### Global TOML Settings

Rather than passing flags for every command, persist the setting in `~/.config/container/config.toml`. The `ContainerSystemConfig` struct, defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), loads these values at startup and exposes them through `ContainerSystemConfig` properties.

Create or edit the configuration file:

```bash
cat <<EOF > ~/.config/container/config.toml
[build]
rosetta = true   # Builder VM always uses Rosetta for non-native architectures

[container]
rosetta = true   # Runtime containers automatically enable Rosetta

EOF

```

When `build.rosetta` is true, the builder VM automatically enables translation for AMD64 targets. Similarly, `container.rosetta` controls whether runtime containers use Rosetta by default, as defined in [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift).

### Verifying Configuration

To confirm the settings are active, query the system properties:

```bash
container system property list | grep rosetta

```

Expected output shows both flags enabled:

```

rosetta = true

```

## Summary

- **Rosetta is disabled by default** in `apple/container` to minimize performance overhead on ARM hosts.
- **Use `--rosetta --arch amd64`** to enable translation for specific `container run` or `container build` commands.
- **Set `rosetta = true`** in both `[build]` and `[container]` sections of `~/.config/container/config.toml` to enable it permanently.
- **Multi-architecture builds** require the `--rosetta` flag when including `amd64` targets on Apple Silicon.
- **Architecture validation** occurs automatically in [`Utility.swift`](https://github.com/apple/container/blob/main/Utility.swift), which injects the Rosetta flag when detecting an `arm64` host running `amd64` binaries.

## Frequently Asked Questions

### Do I need Rosetta enabled to run x86-64 containers on Apple Silicon?

Yes. Without the `--rosetta` flag or persistent configuration enabled, attempting to run an AMD64 container on an ARM64 host will fail. The `container` tool requires explicit opt-in because Rosetta translation adds computational overhead that is unnecessary for native ARM64 workloads.

### Where does the `container` CLI store the default Rosetta setting?

The default settings are stored in `~/.config/container/config.toml`. The `ContainerSystemConfig` class, implemented in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), reads the `[build]` and `[container]` sections at startup, applying the `rosetta` boolean to both builder VMs and runtime containers respectively.

### Can I use Rosetta for multi-architecture image builds?

Yes. When building multi-arch images that include `amd64` alongside `arm64`, pass the `--rosetta` flag. The builder VM, configured via [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) (line 168), uses Rosetta to translate x86-64 instructions while constructing the AMD64 image layer, allowing simultaneous native ARM64 builds and translated x86-64 builds on the same host.

### Is there a performance penalty when using Rosetta 2?

Yes. Rosetta 2 translates x86-64 instructions to ARM64 on the fly, which introduces overhead compared to native execution. This is why `apple/container` disables it by default and requires explicit activation via the `--rosetta` flag or configuration file.