Skip to content

Update container CLI install guide #3695

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jasonrandrews merged 2 commits into from
Aug 27, 2026
Merged

Update container CLI install guide #3695

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1a459f5
Update container CLI install guide
jasonrandrews Aug 27, 2026
70b5e9c
Update container CLI install guide
jasonrandrews Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 19 additions & 20 deletions content/install-guides/container.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Container CLI is an open-source command-line tool from Apple for building and ru

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 verify the Container CLI to run Arm Linux containers natively on Apple silicon Macs.
Use this guide to install and verify the Container CLI for running Arm Linux containers natively on Apple silicon Macs.

## Before you begin

Expand All @@ -35,7 +35,7 @@ The expected output is:
arm64
```

{{% notice Note %}}
{{% notice Supported hardware %}}
Container CLI supports only Apple silicon Macs (M1, M2, M3, and M4).
{{% /notice %}}

Expand All @@ -48,40 +48,40 @@ sw_vers -productVersion
The output is similar to:

```output
26.5.1
26.6.1
```

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

## Install Container CLI

To install Container CLI, go to the [GitHub Releases page](https://github.com/apple/container/releases) and download the latest signed `.pkg` installer.

{{% notice Note %}}
The following commands use Container CLI version 1.0.0. The same commands work with other versions. Replace the file used in these steps with the file for your version of choice. To find the latest version, see [GitHub Releases](https://github.com/apple/container/releases).
{{% notice Version %}}
The following commands use Container CLI version 1.3.0. The same commands work with other versions. Replace the file used in these steps with the file for your version of choice. To find the latest version, see [GitHub Releases](https://github.com/apple/container/releases).
{{% /notice %}}

```bash
wget https://github.com/apple/container/releases/download/1.0.0/container-1.0.0-installer-signed.pkg
wget https://github.com/apple/container/releases/download/1.3.0/container-1.3.0-installer-signed.pkg
```

Install the package:

```bash
sudo installer -pkg container-1.0.0-installer-signed.pkg -target /
sudo installer -pkg container-1.3.0-installer-signed.pkg -target /
```

This installs the Container binary at `/usr/local/bin/container`.
The installer places the `container` binary at `/usr/local/bin/container`.

Start the container system service:

```bash
container system start
```

You must start the service to use commands like `build`, `run`, or `push`. It may need to be restarted after rebooting.
You need to start the service before using commands such as `build`, `run`, or `push`. You might need to restart it after rebooting.

The background server process is now running.
The service now runs in the background.

Verify the CLI version:

Expand All @@ -92,20 +92,19 @@ container --version
The output is similar to:

```output
container CLI version 1.0.0 (build: release, commit: ee848e3)
container CLI version 1.3.0 (build: release, commit: d6de569)
```

## Verify installation by building and running a container


In a working directory, create a file named `Dockerfile`:

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

This image prints the system architecture when executed.
The image prints the system architecture when executed.

### Build the image

Expand All @@ -118,7 +117,7 @@ container build -t uname .
The output is similar to:

```output
[+] Building 2.7s (5/5) FINISHED
[+] Building (5/5) FINISHED
uname:latest
```

Expand All @@ -142,8 +141,8 @@ The `--rm` flag cleans up the container after it exits.

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.

{{% notice Note %}}
The following commands are for Docker Hub. The same commands work with any other OCI-compliant registry such as GitHub Container Registry (ghcr.io) or any OCI-compliant registry. Replace `docker.io` with the appropriate registry hostname.
{{% notice Other registries %}}
The following commands are for Docker Hub. The same commands work with any other OCI-compliant registry such as GitHub Container Registry (ghcr.io). Replace `docker.io` with the appropriate registry hostname.
{{% /notice %}}

Tag the image with a registry-compatible name:
Expand Down Expand Up @@ -191,14 +190,14 @@ To uninstall and retain user data (images and containers):
```bash
uninstall-container.sh -k
```
The command is useful if you plan to reinstall Container CLI later and want to keep your local container data.
Use this option if you plan to reinstall Container CLI later and want to keep your local container data.

Otherwise, to uninstall and delete all user data:

```bash
uninstall-container.sh -d
```

This removes the CLI and all related images, logs, and metadata.
The script removes the CLI and all related images, logs, and metadata.

You’ve now ready to use Container CLI.
You're now ready to use Container CLI.
Loading