# How to Expose Virtualization Capabilities to Containers in Apple Container

> Learn how to expose virtualization capabilities to containers on Apple Silicon M3 and newer. Use the virtualizaton flag with container run or create for nested virtualization.

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

---

**Pass the `--virtualization` flag to `container run` or `container create` to expose host virtualization devices to the guest Linux VM, enabling nested virtualization workloads when running on Apple Silicon M3 or newer.**

The `apple/container` tool runs containers inside lightweight Linux VMs using macOS's Virtualization and vmnet frameworks. By default, these VMs cannot access hardware-assisted virtualization, but you can expose virtualization capabilities to containers by enabling a specific configuration flag that propagates through the runtime to the underlying hypervisor.

## Configuration Architecture

The virtualization exposure mechanism relies on a Boolean flag that travels from the command-line interface through the configuration layer to the low-level VM runtime.

### Container Configuration Structure

In [`Sources/ContainerResource/Container/ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Container/ContainerConfiguration.swift), the `ContainerConfiguration` struct defines a `virtualization` property that controls whether the guest VM receives access to host virtualization devices. This Boolean flag is encoded and decoded from the container's JSON/YAML manifest at lines 49-50, serving as the authoritative source for the runtime's nested virtualization behavior.

### CLI Flag Definition

The command-line interface exposes this capability through the `--virtualization` option. In [`Sources/Services/ContainerAPIService/Client/Flags.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) (lines 343-345), the flag is documented as "Expose virtualization capabilities to the container (requires host and guest support)". This option is available for both `container run` and `container create` commands, allowing users to specify virtualization requirements at container creation time.

## Runtime Propagation

When the container manager constructs the VM configuration, the flag value propagates from the high-level configuration into the low-level hypervisor settings.

In [`Sources/Services/RuntimeLinux/Server/RuntimeService.swift`](https://github.com/apple/container/blob/main/Sources/Services/RuntimeLinux/Server/RuntimeService.swift) at line 993, the implementation assigns the configuration value directly to the VM configuration: `czConfig.virtualization = config.virtualization`. This assignment passes the request to Apple's Virtualization framework, which then determines whether to forward virtualization-related capabilities (such as KVM device access) to the guest VM based on host hardware capabilities.

## Platform Requirements and Validation

Enabling nested virtualization imposes specific hardware and software constraints that the runtime validates before VM initialization.

### Hardware Prerequisites

Nested virtualization requires **Apple Silicon M3 or newer** Macs. The host must support the underlying virtualization extensions that macOS exposes through the Virtualization framework. If the host hardware lacks this support, the runtime returns an explicit error before attempting to boot the VM.

### Error Handling

When the `--virtualization` flag is used on unsupported hardware, the container runtime returns the following error as documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 525-529):

```

Error: unsupported: "nested virtualization is not supported on the platform"

```

This validation occurs early in the container lifecycle, preventing the allocation of resources for workloads that cannot execute.

### Kernel Verification

After successfully launching a container with virtualization enabled, verify availability inside the guest by checking for KVM driver detection:

```bash
dmesg | grep kvm

```

Expected output on supported systems includes references to nested virtualization support:

```

[    0.000000] kvm: nested=1
[    0.123456] kvm: hv_evtchn: using host event channel

```

The guest Linux kernel must include the appropriate virtualization options enabled, as detailed in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 518-520).

## Usage Examples

The following examples demonstrate correct usage patterns for exposing virtualization capabilities in supported environments.

### Basic Nested Virtualization

To expose virtualization capabilities to a new container, include the `--virtualization` flag along with a kernel that supports KVM:

```bash
container run \
    --name my-nested-vm \
    --virtualization \
    --kernel /path/to/linux-kernel-with-kvm-support \
    ubuntu:latest \
    sh -c "dmesg | grep kvm"

```

This command requests that the Virtualization framework expose the host's virtualization device to the guest, allowing the container to run its own VM-based workloads.

### Handling Unsupported Platforms

When running on incompatible hardware, the command fails fast with a descriptive error:

```bash
container run \
    --name test \
    --virtualization \
    ubuntu:latest \
    sh -c "echo hello"

```

Output:

```

Error: unsupported: "nested virtualization is not supported on the platform"

```

## Summary

- **Configuration flag**: The `virtualization` Boolean in [`ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/ContainerConfiguration.swift) controls exposure of host virtualization devices.
- **CLI interface**: Use `--virtualization` with `container run` or `container create` to request nested virtualization.
- **Runtime propagation**: The flag passes through [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) to `czConfig.virtualization`, which configures the Apple Virtualization framework.
- **Hardware requirements**: Requires Apple Silicon M3 or newer; unsupported hardware produces explicit error messages.
- **Verification**: Check `dmesg | grep kvm` inside the container to confirm KVM driver detection.

## Frequently Asked Questions

### What hardware is required to expose virtualization capabilities to containers?

Nested virtualization requires an Apple Silicon M3 chip or newer. The host must support the virtualization extensions that macOS exposes through the Virtualization framework. Older Apple Silicon chips or Intel-based Macs do not support this feature, and attempting to use the `--virtualization` flag on these platforms results in an "unsupported" error before the container boots.

### How does the `--virtualization` flag propagate from the command line to the VM?

The flag flows through three architectural layers: first, it is parsed in [`Flags.swift`](https://github.com/apple/container/blob/main/Flags.swift) and stored in the client configuration; second, it is serialized into the `ContainerConfiguration` struct in [`ContainerConfiguration.swift`](https://github.com/apple/container/blob/main/ContainerConfiguration.swift); third, it is copied to `czConfig.virtualization` in [`RuntimeService.swift`](https://github.com/apple/container/blob/main/RuntimeService.swift) at line 993, where the Apple Virtualization framework receives the request to expose host virtualization devices to the guest Linux VM.

### How can I verify that virtualization is working inside the container?

After starting a container with the `--virtualization` flag, run `dmesg | grep kvm` inside the container. If the host supports nested virtualization and the guest kernel includes the appropriate drivers, you will see output indicating KVM detection, such as `kvm: nested=1`. Absence of this output suggests either unsupported hardware or a guest kernel lacking virtualization modules.

### Can I use the `--virtualization` flag with any container image?

Yes, the flag works with any container image, but the guest must include a Linux kernel with KVM support enabled to utilize the exposed virtualization capabilities. The kernel must be built with the appropriate virtualization configuration options, as documented in the [`how-to.md`](https://github.com/apple/container/blob/main/how-to.md) guide at lines 518-520. Without a compatible kernel, the container runs but cannot instantiate nested VMs.