Prerequisites for Installing Apple's Container Runtime: Hardware, OS, and Build Requirements

Apple's container runtime requires an Apple Silicon Mac running macOS 26 or newer, Xcode 26 with the Swift 5.9+ toolchain, and administrator privileges to install binaries to /usr/local.

The apple/container repository provides a macOS-native container runtime that executes Linux containers inside lightweight virtual machines. Before installing the pre-built package or compiling from source, your system must meet specific hardware, operating system, and development toolchain prerequisites as defined in the project's README.md and BUILDING.md files.

Hardware and Operating System Prerequisites

Apple Silicon Mandate

The runtime only supports Apple Silicon Macs (M1, M2, and subsequent generations). According to the README.md specifications, Intel-based Macs are explicitly unsupported due to the architecture's incompatibility with the Virtualization framework features required for container execution.

macOS Version Compatibility

You must run macOS 26 or newer to access the full feature set. While macOS 15 receives limited support, the current release targets macOS 26 specifically for its enhanced Virtualization and vmnet framework capabilities documented in docs/technical-overview.md. The operating system must provide the Virtualization framework natively, as the runtime creates per-container VMs using these macOS APIs.

Development Environment Prerequisites

Xcode 26 and Swift Toolchain

Install Xcode 26 and set it as the active developer directory. The build system relies on the Swift toolchain shipped with Xcode 26, specifically Swift 5.9 or newer. The Package.swift file defines the Swift package dependencies and version requirements, while the BUILDING.md file explicitly states that no standalone Swift installation suffices—you must use the toolchain bundled with Xcode 26.

Configure the command-line tools to use this Xcode installation:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Command-Line Tools Configuration

The swift command-line tools are required for package editing, building, and dependency resolution. Verify your Swift installation matches the requirement:

swift --version

This should report Swift 5.9 or newer associated with Xcode 26.

Framework and Permission Prerequisites

Virtualization Framework

macOS 26 includes the Virtualization framework that container uses to create per-container VMs. No additional packages are required, but the framework must be present as part of the operating system. The technical overview at docs/technical-overview.md explains how the runtime integrates with this macOS-native framework without external dependencies like Docker Desktop or VirtualBox.

Network Permissions and Installation Access

Installing the runtime writes helper binaries to /usr/local and may require administrator privileges for service registration. The scripts/install-init.sh script handles placement of binaries under /usr/local/bin, requiring sudo access during the installation process.

Optional Build Dependencies

gRPC and Protocol Buffers for Local Image Building

If you plan to build container images locally rather than just running pre-built images, install additional dependencies: grpc-swift and swift-protobuf. The repository includes a make protos target that generates the required gRPC stubs from Protocol Buffer definitions. These dependencies are only necessary when compiling the full build pipeline, not for running the standard runtime.

Installation Methods

Pre-built Package Installation

Download the signed installer from the releases page for the simplest setup:

# Download the latest signed installer (replace <version> with the desired tag)

curl -L -o container.pkg "https://github.com/apple/container/releases/download/<version>/container.pkg"

# Install the package (requires admin password)

sudo installer -pkg container.pkg -target /

# Verify the binary is in /usr/local/bin

/usr/local/bin/container --version

This method automatically places the container binary and its helpers in /usr/local/bin via the scripts/install-init.sh logic.

Building from Source

For custom builds or development work, compile directly from the repository:

# Clone the repository

git clone https://github.com/apple/container.git
cd container

# Ensure Xcode 26 is the active developer directory

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

# Build the tool and its helpers

make APP_ROOT=~/projects/container all test integration

# Install the binaries to /usr/local (requires admin password)

sudo make install

The BUILDING.md file specifies these exact steps, noting that the make command compiles the Swift source using the Xcode 26 toolchain.

Post-Installation Verification

Starting the System Service

Before running any container commands, start the background services:

# Start the background services

container system start

# Check the status

container system version

Running Your First Container

Verify the installation by pulling and running a Linux container:

# Pull a tiny Linux image from Docker Hub

container pull docker.io/alpine:latest

# Run a one-off container that prints its OS release

container run --rm alpine:latest cat /etc/os-release

This confirms the Virtualization framework is properly accessible and the runtime can execute Linux containers inside the lightweight VM.

Summary

• Apple Silicon is mandatory: The runtime only supports M1/M2 Macs, excluding Intel-based systems entirely.
• macOS 26 required: Full functionality requires macOS 26 for Virtualization framework enhancements; macOS 15 offers limited support only.
• Xcode 26 is non-negotiable: You must install Xcode 26 and use its bundled Swift 5.9+ toolchain, as specified in BUILDING.md and Package.swift.
• Administrator access needed: Installation writes to /usr/local via scripts/install-init.sh and registers system services.
• Optional build tools: Local image building requires grpc-swift and swift-protobuf with the make protos target.

Frequently Asked Questions

Can I run Apple container on Intel-based Macs?

No. According to the README.md requirements, the runtime explicitly requires Apple Silicon (M1/M2/...) and does not support Intel-based Macs. The architecture relies on specific Virtualization framework features available only on Apple Silicon.

Is macOS 15 sufficient for running the container runtime?

macOS 15 is supported only with limited functionality. The current release targets macOS 26 specifically, which provides necessary Virtualization and vmnet framework enhancements required for full container operation.

Do I need to install Swift separately from Xcode?

No. The build system requires the Swift toolchain shipped specifically with Xcode 26. While Swift 5.9+ is required, you must use the version bundled with Xcode 26, not a standalone Swift installation, as the BUILDING.md file emphasizes.

What if I only want to run containers, not build images?

You can install the pre-built package without additional dependencies. The optional grpc-swift and swift-protobuf requirements only apply if you plan to build container images locally using the make protos target. For running existing images, only the core runtime installed to /usr/local/bin is necessary.

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