How to Install Apple's Container Runtime on macOS: A Complete Guide

TLDR: Download the signed .pkg from GitHub Releases, install it to /usr/local, then run container system start to initialize the Virtualization-based runtime.

Apple's container tool provides a lightweight Linux container experience on macOS by running each container inside its own minimal virtual machine. Available in the apple/container repository, this runtime leverages macOS's Virtualization and vmnet frameworks to execute privileged VM operations. Installing Apple's container runtime on macOS requires a signed installer package and administrator privileges to configure the XPC-based system service.

Prerequisites and System Requirements

macOS Version Compatibility

The runtime requires macOS 26 or later to access the newest virtualization features. It will also run on macOS 15, but some network-related commands are disabled due to platform limitations.

Privilege Requirements

Because the runtime executes privileged VM operations, the installer must be signed and placed under /usr/local so that the system service can be started with administrator privileges. The installation process uses Launch Daemons for service management and XPC for inter-process communication.

Installation Steps

Download the Signed Installer Package

Visit the GitHub Releases page and download the latest container-*.pkg file. For example, to download version 0.4.1 via command line:

curl -L -o container.pkg \
  https://github.com/apple/container/releases/download/v0.4.1/container-0.4.1.pkg

Run the macOS Installer

Double-click the .pkg file and follow the UI prompts. You will be prompted for an administrator password. According to the repository's README.md, the installer copies the container binary and helper scripts to /usr/local/bin and /usr/local/libexec.

Start the System Service

After installation, launch the system service using the container system start command. This initiates the container-apiserver launch-agent, which spawns XPC helpers including container-core-images, container-network-vmnet, and container-runtime-linux for image management, networking, and container execution.

container system start

Verification and Post-Installation

Verify the installation by checking the version and running a test container:

container version
container run --rm hello-world

The runtime reads configuration from ~/.config/container/config.toml. You can customize VM memory, CPU allocation, or the init image by editing this file as documented in BUILDING.md.

Upgrade and Uninstall

To upgrade to a newer version, use the bundled script installed at /usr/local/bin/update-container.sh:

/usr/local/bin/update-container.sh

To remove the runtime completely, run the uninstall script with the -d flag for full removal or -k to keep user data:

/usr/local/bin/uninstall-container.sh -d

For maintenance operations, always stop the service before upgrading or uninstalling:

container system stop

Summary

• Apple's container runtime requires macOS 15 or later (macOS 26 recommended) and installs to /usr/local using a signed .pkg installer.
• After installation, you must run container system start to initialize the Virtualization-based service and XPC helpers.
• Verify functionality with container version and container run --rm hello-world.
• Use update-container.sh for upgrades and uninstall-container.sh -d for complete removal.

Frequently Asked Questions

What macOS versions are supported for installing Apple's container runtime?

The runtime requires macOS 26 or later for full functionality, including all networking features. It will run on macOS 15, but some network-related commands are disabled due to platform limitations as noted in the technical overview.

Why does the installer require administrator privileges?

The runtime executes privileged VM operations using macOS's Virtualization and vmnet frameworks. The installer places binaries under /usr/local/bin and /usr/local/libexec, then configures Launch Daemons that require root access to manage the virtual machines and network interfaces.

How do I troubleshoot if the container service won't start?

First, ensure you have started the service with container system start. You can check the status of the apiserver using launchctl list | grep container. If upgrading or uninstalling, always run container system stop first to ensure clean termination of the XPC helpers like container-core-images and container-network-vmnet.

Can I customize the VM resources allocated to containers?

Yes. The runtime reads configuration from ~/.config/container/config.toml. You can edit this file to customize VM memory, CPU allocation, or the init image according to the specifications in BUILDING.md.

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