Container CLI for macOS

Container CLI is an open-source command-line tool from Apple for building and running Arm Linux containers directly on macOS. With Container CLI, you can run containers using lightweight virtual machines without Docker Desktop or full Linux VMs.

The CLI supports the full Open Container Initiative (OCI) workflow: building, running, tagging, and pushing container images.

In this guide, you’ll learn how to install and use the Container CLI to run Arm Linux containers natively on Apple silicon Macs.

Before you begin

First, confirm you are using an Apple silicon Mac by running:

    

        
        
uname -m

    

The output should be:

    

        
        arm64

        
    

Check your macOS version:

    

        
        
sw_vers -productVersion

    

Example output:

    

        
        15.6.1

        
    

You must run macOS 15.0 or later to use the Container CLI.

Install Container CLI

To install Container CLI, go to the GitHub Releases page and download the latest signed .pkg installer.

For example, the following commands use version 0.11.0. Replace 0.11.0 with the latest version:

    

        
        
wget https://github.com/apple/container/releases/download/0.11.0/container-0.11.0-installer-signed.pkg

    

Install the package:

    

        
        
sudo installer -pkg container-0.11.0-installer-signed.pkg -target /

    

This installs the Container binary at /usr/local/bin/container.

Start the container system service:

    

        
        
container system start

    

You must start the service to use commands like build, run, or push. It may need to be restarted after rebooting.

The background server process is now running.

Verify the CLI version:

    

        
        
container --version

    

The output is similar to:

    

        
        container CLI version 0.11.0 (build: release, commit: d9b8a8d)

        
    

Verify installation by building and running a container

In a working directory, create a file named Dockerfile:

    

        
        
FROM ubuntu:latest
CMD echo -n "Architecture is " && uname -m

    

This image prints the system architecture when executed.

Build the image

Run the following to build and tag the container image as uname:

    

        
        
container build -t uname .

    

Example output:

    

        
        Successfully built uname:latest

        
    

Run the container

Run the container to verify it prints the system architecture.

    

        
        
container run --rm uname

    

Expected output:

    

        
        Architecture is aarch64

        
    

The --rm flag cleans up the container after it exits.

Tag and push the image

After the image is built and tested locally, you can push it to a container registry such as Docker Hub. This allows the image to be reused across machines or shared with others.

Tag the image with a registry-compatible name:

    

        
        
container images tag uname docker.io/<your-username>/uname:latest

    

Replace <your-username> with your Docker Hub username.

Log in to Docker Hub:

    

        
        
container registry login docker.io

    

Enter your Docker Hub username and password.

Next, upload the tagged image to Docker Hub:

    

        
        
container images push docker.io/<your-username>/uname:latest

    

List images and containers

To view images:

    

        
        
container images ls

    

To view running or stopped containers:

    

        
        
container ls

    

Uninstall the Container CLI

The CLI includes an uninstall script. You can choose whether to keep or delete your container data.

To uninstall and retain user data (images and containers):

    

        
        
uninstall-container.sh -k

    

The command is useful if you plan to reinstall Container CLI later and want to keep your local container data.

Otherwise, to uninstall and delete all user data:

    

        
        
uninstall-container.sh -d

    

This will remove the CLI and all related images, logs, and metadata.

You’ve now ready to use Container CLI.