Skip to main content

​
Installation

This guide will walk you through installing, upgrading, and uninstalling Container CLI on your Mac.

​
Requirements

Before installing container, ensure your system meets these requirements:
  • Mac with Apple silicon
  • macOS 26 or later
  • Administrator access (for installation)
Container CLI is supported on macOS 26, since it takes advantage of new features and enhancements to virtualization and networking in this release. Older versions of macOS are not supported.

​
Initial install

1

Download the installer

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

Run the installer

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

Start the system service

Open a terminal and start the container service:
container system start
If you have not installed a Linux kernel yet, the command will prompt you to install one:
% container system start

Verifying apiserver is running...
Installing base container filesystem...
No default kernel configured.
Install the recommended default kernel from [https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz]? [Y/n]: y
Installing kernel...
%
4

Verify the installation

Verify that the application is working by running a command to list all containers:
container list --all
If you haven’t created any containers yet, the command outputs an empty list:
% container list --all
ID  IMAGE  OS  ARCH  STATE  ADDR
%
The installer places files under /usr/local/bin and /usr/local/libexec. Make sure /usr/local/bin is in your PATH.

​
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).

​
Upgrade to latest version

1

Stop the container service

If you’re upgrading, you must stop your existing container:
container system stop
2

Run the update script

For upgrading to the latest release version, simply run:
/usr/local/bin/update-container.sh
3

Start the container service

Start the system service with the new version:
container system start

​
Downgrade to specific version

1

Stop the container service

Stop your existing container:
container system stop
2

Uninstall current version

Uninstall your existing container. The -k flag keeps your user data, while -d removes it:
/usr/local/bin/uninstall-container.sh -k
3

Install specific version

Use the update script with the -v flag to specify the version:
/usr/local/bin/update-container.sh -v 0.3.0
4

Start the container service

Start the system service:
container system start

​
Uninstall

Use the uninstall-container.sh script (installed to /usr/local/bin) to remove container from your system. 
/usr/local/bin/uninstall-container.sh -d
To retain your user data so that it is available should you reinstall later, use the -k flag. To remove your user data along with the tool, use the -d flag.

​
Building from source

If you want to build container from source instead of using the installer, you’ll need:
  • Mac with Apple silicon
  • macOS 15 minimum, macOS 26 recommended
  • Xcode 26, set as the active developer directory

​
Build and install

1

Clone the repository

Clone the container repository to your local machine:
git clone https://github.com/apple/container.git
cd container
2

Build the project

Build container and run tests:
make all test integration
For a release build with better performance:
BUILD_CONFIGURATION=release make all test integration
3

Install the binaries

Copy the binaries to /usr/local/bin and /usr/local/libexec (requires entering an administrator password):
make install
Or for a release build:
BUILD_CONFIGURATION=release make install
There is a bug in the vmnet framework on macOS 26 that causes network creation to fail if the container helper applications are located under your Documents or Desktop directories. If you prefer to use the binaries that make all creates in your project bin and libexec directories, locate your project elsewhere, such as ~/projects/container, until this issue is resolved.

​
Next steps

Now that you have Container CLI installed, proceed to the quick start guide to run your first container.

Build docs developers (and LLMs) love

Get started for freeTalk to us