# How to Use Rosetta Translation Within arm64 Containers on macOS

> Learn how to enable Rosetta 2 translation within arm64 containers on macOS for Apple Silicon. Execute x86-64 binaries effortlessly with the --rosetta flag or config.toml setting.

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

---

**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`](https://github.com/apple/container/blob/main/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.

```bash

# 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`](https://github.com/apple/container/blob/main/docs/container-system-config.md), the `rosetta` property under the `[build]` section controls global defaults.

```bash

# 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`](https://github.com/apple/container/blob/main/docs/how-to.md) file demonstrates this verification technique using the `uname` command.

Run an amd64 binary with Rosetta enabled:

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

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

```

Compare with a native arm64 execution:

```bash
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`](https://github.com/apple/container/blob/main/docs/how-to.md)**: Demonstrates Rosetta behavior with practical `uname` examples and explains the translation mechanism
- **[`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md)**: Lists the `rosetta` configuration property and documents its default value of `true`
- **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/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.