Skip to content
Merged
Changes from all commits
Commits
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
114 changes: 48 additions & 66 deletions content/install-guides/container.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,42 @@
---
title: Container CLI for macOS

draft: true

author: Rani Chowdary Mandepudi

minutes_to_complete: 10

official_docs: https://github.com/apple/container

additional_search_terms:
- container
- virtualization

- container
- virtualization
layout: installtoolsall
multi_install: false
multitool_install_part: false
test_maintenance: false
weight: 1
---

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 the need for Docker Desktop or Linux VMs.
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 article provides a step-by-step guide to install and use the `container` command-line tool for building and running Arm Linux containers natively on macOS systems with Apple silicon.
This guide shows how to install and use the `container` CLI to run Arm Linux containers natively on Apple silicon Macs.

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

```bash
uname -m
```

The output on macOS is:
Expected output:

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

Container CLI only works on Macs with Apple silicon, including M1, M2, M3, and M4.

Use the following command to verify macOS version:
Check your macOS version:

```bash
sw_vers -productVersion
Expand All @@ -54,37 +48,35 @@ Example output:
15.5
```

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

## How do I install Container CLI?

To install Container CLI on macOS, follow the steps below:
To install Container CLI:

From the [official GitHub Release page](https://github.com/apple/container/releases), download the latest signed `.pkg` installer.
Go to the [GitHub Releases page](https://github.com/apple/container/releases) and download the latest signed `.pkg` installer.

For example:

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

Install the downloaded package using:
Install the package:

```bash
sudo installer -pkg container-0.2.0-installer-signed.pkg -target /
```

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

After installation, start the container system service by running the following command:
Start the container system service:

```bash
container system start
```

{{% notice Note %}}
The system service must be running to use container operations such as build, run, or push. It may also need to be started again after a reboot, depending on system settings.
{{% /notice %}}
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.

Expand All @@ -97,119 +89,109 @@ container --version
Example output:

```output
container CLI version 0.2.0
container CLI version 0.2.0
```

This confirms that the Container CLI is successfully installed and ready to use.

## How do I build, run, and push a container using the Container CLI?

### Create a Dockerfile
## Build and run a container

You can define a simple image that prints the system architecture.

Use an editor to create a file named `Dockerfile` with the following contents:
In a working directory, create a file named `Dockerfile`:

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

### Build the container image
This image prints the system architecture when executed.

Build the image from the `Dockerfile`.
### Build the image

This will pull the Ubuntu base image and tag the result as `uname`.
Run the following to build and tag the container image as `uname`:

```bash
container build -t uname .
```

The output will be similar to:
Example output:

```output
Successfully built uname:latest
```

### Run the container
### Run the container

Execute the container to verify it runs successfully and prints the system architecture.
Run the container to verify it prints the system architecture.

```bash
```bash
container run --rm uname
```

The output is:
Expected output:

```output
Architecture is aarch64
```

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

### Tag and push the image
## 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.

Use the `tag` command to apply a registry-compatible name to the image:
Tag the image with a registry-compatible name:

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

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

Before pushing the image, log in to Docker Hub:
Log in to Docker Hub:

```bash
```bash
container registry login docker.io
```

Enter your Docker Hub username and password.

{{% notice Note %}}
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.
{{% /notice %}}

Next, upload the tagged image to Docker Hub.
Next, upload the tagged image to Docker Hub:

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

Once the push completes successfully, the image will be available in the Docker Hub repository. It can be pulled and run on other systems that support the Arm architecture.

## How can I list images and containers?
## List images and containers

You can view locally built or pulled images using:
To view images:

```bash
```bash
container images ls
```

To see running or previously executed containers:
To view running or stopped containers:

```bash
container ls
```

## How do I uninstall the Container CLI?

The Container CLI includes an uninstall script that allows you to remove the tool from your system. You can choose to remove the CLI with or without user data.
The CLI includes an uninstall script. You can choose whether to keep or delete your container data.

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

```bash
```bash
uninstall-container.sh -k
```

Use this if you plan to reinstall later and want to preserve your local container data.

Uninstall and delete all user data:
Otherwise, to uninstall and delete all user data:

```bash
uninstall-container.sh -d
```
This will permanently remove the CLI and all container images, logs, and metadata.

You can now build and run Arm Linux containers on macOS.
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.