What Linux Distributions Are Supported by Apple Container Runtime?

Apple Container Runtime supports any OCI-compatible Linux distribution that provides a /sbin/init executable, with Alpine, Ubuntu, and Debian being the first-class examples documented in the project's tutorials.

The apple/container repository provides a lightweight container runtime for macOS that executes Linux containers inside virtual machines using the macOS Virtualization framework. Unlike traditional container engines that restrict you to specific host kernel versions, this runtime can theoretically run any Linux distribution meeting minimal OCI image standards. In practice, the documentation highlights three primary distributions as canonical examples for creating persistent container machines.

First-Class Linux Distributions

The project explicitly identifies three target distributions in the container machine documentation. According to docs/container-machine.md, these represent the "one environment per target distro" concept used throughout the tutorials.

Alpine Linux

Alpine Linux serves as the default quick-start example due to its minimal musl-based footprint. The documentation uses Alpine images for rapid prototyping and basic functionality demonstrations, making it the go-to choice for testing the runtime.

Ubuntu

Ubuntu appears in the "Ubuntu container-machine" Dockerfile and the VS Code development example at examples/container-machine-vscode/README.md. This full-featured Debian derivative demonstrates developing inside a container machine with standard IDE integration, representing a typical development workflow.

Debian

Debian is listed alongside Alpine and Ubuntu as a supported target distro in the same documentation files, providing a stable alternative for users preferring the Debian ecosystem over Ubuntu's release cycle.

Generic OCI Compatibility Requirements

Beyond the three first-class examples, the runtime accepts any Linux OCI image containing a classic init system. As implemented in the Virtualization framework integration, the container machine boots the image's init process as PID 1.

Requirements for any Linux distribution:

1. OCI-compatible image format (built with docker build or container build)
2. /sbin/init executable present in the image root
3. Kernel configuration for nested virtualization: CONFIG_KVM=y (the default kernel lacks this option), as noted in docs/container-machine.md lines 75-81

This means you can run Fedora, CentOS, openSUSE, Arch, or custom Linux builds satisfying these criteria.

Creating Container Machines with Different Distros

The container machine create command accepts any compatible OCI image reference. Here are the documented patterns for the three primary distributions:

# Create an Alpine-based container machine (quick-start default)

container machine create alpine:latest --name alpine-dev

# Create an Ubuntu-based container machine (used in VS Code examples)

container machine create ubuntu:24.04 --name ubuntu-dev

# Create a Debian-based container machine

container machine create debian:stable --name debian-dev

You can also run ephemeral containers without persisting a machine:

# Run a command in Alpine without creating a persistent machine

container run -it --name my-alpine alpine:latest uname -a

# Check OS release in Ubuntu

container run -it --name my-ubuntu ubuntu:24.04 cat /etc/os-release

Technical Architecture and Limitations

The runtime's flexibility stems from its VM-based architecture described in docs/technical-overview.md. By booting a full Linux virtual machine for each container machine, the system avoids host-kernel compatibility issues typical of Linux container runtimes on macOS.

Key implementation details from docs/how-to.md and Package.swift:

• The Swift package bundles the low-level containerization framework used to manage the virtualization layer
• The VM expects the init process at /sbin/init to start OS services as PID 1
• Nested virtualization requires specific kernel configuration changes mentioned in the technical documentation

Summary

• Apple Container Runtime supports any OCI-compatible Linux distribution with /sbin/init
• Alpine, Ubuntu, and Debian are the three first-class distributions documented in docs/container-machine.md
• The runtime creates lightweight VMs using the macOS Virtualization framework, allowing generic Linux compatibility
• Nested virtualization requires CONFIG_KVM=y kernel support
• Commands like container machine create and container run work with any compatible OCI image reference

Frequently Asked Questions

Can I run Fedora or CentOS with Apple Container Runtime?

Yes. The runtime accepts any OCI-compatible Linux image that contains /sbin/init. You can create a machine with container machine create fedora:latest --name fedora-dev or substitute CentOS, openSUSE, Arch, or custom builds meeting the basic requirements.

What is the default Linux distribution used in Apple Container examples?

Alpine Linux serves as the default example in the quick-start documentation due to its minimal size and fast boot characteristics. The alpine:latest image appears in the basic container machine create examples throughout the tutorials.

Does Apple Container Runtime require specific kernel versions for the Linux distributions?

The runtime does not enforce specific distribution kernel versions, but for nested virtualization scenarios, you need a kernel compiled with CONFIG_KVM=y. The default kernel configuration used by the runtime does not include this option, as documented in docs/container-machine.md.

How do I create a development environment with Ubuntu in Apple Container Runtime?

Create a persistent machine using container machine create ubuntu:24.04 --name ubuntu-dev, then follow the VS Code integration example in examples/container-machine-vscode/README.md to attach your IDE to the running container machine.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}