README.md

container

container is a tool that you can use to create and run Linux containers as lightweight virtual machines on your Mac. It's written in Swift, and optimized for Apple silicon.

The tool consumes and produces OCI-compatible container images, so you can pull and run images from any standard container registry. You can push images that you build to those registries as well, and run the images in any other OCI-compatible application.

container uses the Containerization Swift package for low-level container, image, and process management.

The stephenlclarke fork supplies the runtime and CLI for the matched container-compose release stack. That repository owns the canonical stack map, current dependency pins, and release policy. container system version reports the exact runtime, containerization, and builder-shim revisions in an installed package.

As of 15 September 2026, source-bearing main revision ef78345f59fd passes the merge build, SonarQube, signed Prebuilt Binaries, and downstream matched-stack publication. Recent exact-main SonarQube analyses report an OK quality gate and 61.8–61.9% aggregate coverage; the tenth-point variation comes from repeated instrumented runs of unchanged source. They report 2.4% duplicated lines, 121,453 lines of code, and zero bugs, vulnerabilities, code smells, or security hotspots, with A reliability, security, and maintainability ratings. Coverage is materially below the Container-family's approximately 90% objective and remains an explicit quality gap; the green quality gate must not be read as 90% coverage.

Get started

Requirements

You need a Mac with Apple silicon to run container. To build it, see the BUILDING document.

container is supported on macOS 26, since it takes advantage of new features and enhancements to virtualization and networking in this release. We do not support older versions of macOS and the container maintainers typically will not address issues that cannot be reproduced on macOS 26.

Initial install

Download the latest signed installer package for container from the GitHub release page.

To install the tool, double-click the package file and follow the instructions. Enter your administrator password when prompted, to give the installer permission to place the installed files under /usr/local.

The stephenlclarke fork also publishes a prebuilt Homebrew package. Follow HOMEBREW.md for the supported matched-stack install path.

Start the system service with:

container system start

Run your first container

container run --rm alpine echo hello

This pulls the alpine image, runs it in a lightweight Linux VM, prints hello, and removes the container when it exits. See the tutorial for a fuller walkthrough that builds and publishes an image of your own.

Network interface names

When attaching a network, interface=NAME assigns a stable name to its interface inside the Linux guest. For example:

container run --network default,interface=frontend alpine:latest ip link show frontend

Additional interface addresses

Repeat address=IP in a network attachment to configure additional IPv4 or IPv6 addresses inside the guest. Addresses without an explicit prefix use Docker-compatible address masks (/16 for IPv4 and /64 for IPv6):

container run \
  --network default,address=198.51.100.8,address=2001:db8::8/64 \
  alpine:latest ip address show

Requested primary interface addresses

Use ip=IPv4 or ip6=IPv6 in a network attachment to request its primary address. The address must be an allocatable member of the network's configured subnet; the network service reserves it so later dynamic allocations cannot reuse it. Values are addresses, not CIDRs:

container run --network backend,ip=192.0.2.8,ip6=2001:db8::8 alpine:latest ip address show eth0

Upgrade or downgrade

For both upgrading and downgrading, you can manually download and install the signed installer package by following the steps from initial install or use the update-container.sh script (installed to /usr/local/bin).

If you're upgrading or downgrading, you must stop your existing container:

container system stop

To upgrade to the latest release, simply run the command below:

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

To downgrade, you must uninstall your existing container (the -k flag keeps your user data, while -d removes it):

/usr/local/bin/uninstall-container.sh -k
/usr/local/bin/update-container.sh -v MAJOR.MINOR.PATCH

Start the system service with:

container system start

Uninstall

Use the uninstall-container.sh script (installed to /usr/local/bin) to remove container from your system. To remove your user data along with the tool, run:

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

To retain your user data so that it is available should you reinstall later, run:

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

Next steps

• Take a guided tour of container by building, running, and publishing a simple web server image.
• Learn how to use various container features.
• Read a brief description and technical overview of container.
• Browse the full command reference.
• Build and run container on your own development system.
• View the fork's DocC API reference in the integrated container developer documentation.
• Compare the Apple upstream API reference.

Contributing

Contributions to container are welcome and encouraged. Please see our main contributing guide for more information.

make coverage-sonar runs the instrumented unit suite and emits project-confined LCOV plus SonarQube generic XML. make sonar-scan submits that report with the exact current commit as the previous-version baseline; the hosted workflow performs both steps for pull requests and main.

Project Status

The container project is under active development. Its release versions are product versions, not semantic versions.

The container CLI compatibility generally preserves backward compatibility within a major release (not breaking existing scripts), however, there may be the odd case where breaking compatibility may be necessary. Note: Features marked experimental (for example, the k8s subcommand) may change and do not guarantee backward compatibility.

The container-apiserver XPC API compatibility preserves forward and backward compatibility within a major version. Other non-public XPC helpers do not guarantee CLI or API compatibility across different versions.

The container application data provides forward compatibility only, guaranteed within one major version. Upgrading to a newer major version may require a specific upgrade path.