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

> Install Apple's container runtime on macOS with this complete guide. Download the signed pkg from GitHub Releases and start the virtualization-based runtime for seamless container management.

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

---

**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](https://github.com/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:

```bash
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.

```bash
container system start

```

## Verification and Post-Installation

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

```bash
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`](https://github.com/apple/container/blob/main//usr/local/bin/update-container.sh):

```bash
/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:

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

```

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

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