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 using lightweight virtual machines without Docker Desktop or full Linux VMs.

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

What should I do before installing the Container CLI?

This guide shows how to install and use the container CLI to run Arm Linux containers natively on Apple silicon Macs.

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

    

        
        
uname -m

    

Expected output:

    

        
        arm64

        
    

Check your macOS version:

    

        
        
sw_vers -productVersion

    

Example output:

    

        
        15.5

        
    

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

How do I install Container CLI?

To install Container CLI:

Go to the GitHub Releases page and download the latest signed .pkg installer.

For example:

    

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

    

Install the package:

    

        
        
sudo installer -pkg container-0.2.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

    

Example output:

    

        
        container CLI version 0.2.0

        
    

Build and run 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

Once the image is built and tested locally, it can be pushed 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.

The same command works with other registries such as GitHub Container Registry (ghcr.io) or any OCI-compliant registry. Replace docker.io with the appropriate registry hostname.

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

    

How do I uninstall the Container CLI?

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

If you plan to reinstall later and want to keep your local container data. To uninstall and keep user data (images and containers):

    

        
        
uninstall-container.sh -k

    

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 installed Container CLI and built your first Arm Linux container on macOS.