README

 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.

!introductory movie showing some basic commands

 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.

Start the system service with:

bash
container system start


 Run your first container

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

 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:

bash
container system stop


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

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

bash
/usr/local/bin/uninstall-container.sh -k
/usr/local/bin/update-container.sh -v 0.3.0


Start the system service with:

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

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


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

bash
/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.
- Explore the container-examples repo that contains examples that show you how to work with c

Top issues

Discussions

Latest release

Highlights

⌨️ denotes breaking CLI changes.

👩‍💻 denotes breaking API changes.

- Core
  - container stats now reports cpuUtilization in JSON, YAML, and TOML output
  - Image snapshots and container filesystems are now excluded from Time Machine backups
  - Default Kata kernel is now 4.3.1 (vmlinux-6.18.56-208-debug)
  - Updated Containerization to 0.54.0
- Networking
  - Default DNS nameservers, search domains, and options can now be set in config.toml
- Build
  - Fixed container build failures with newer BuildKit and missing build context for steps that need the full context