How to Use Apple container: A Step-by-Step Guide to Running Linux Containers on Mac

Jun 12, 2026

Purpose

This post walks through the complete workflow of installing Apple container and running your first Linux container on an Apple Silicon Mac.

Installation

Download the signed installer from the GitHub releases page. Double-click the .pkg file to install it to /usr/local.

container --version

After installation, start the background service:

container system start

This launches the container-apiserver and its helper processes.

To upgrade later:

/usr/local/bin/update-container.sh

To uninstall while keeping user data:

/usr/local/bin/uninstall-container.sh -k

First Container

Verify the service is running:

container ls

An empty list means the service is ready.

Build an Image

Create a Dockerfile:

FROM python:3.12-slim
WORKDIR /app
COPY app.py .
CMD ["python", "app.py"]

Build the image:

container build -t web-test --file Dockerfile .

Terminal output showing a successful container build with layer hashes and a 'Successfully tagged web-test' message

Run the Container

Start a container from the image:

container run --name my-web-server --detach --rm web-test

Check that it is running:

container ls -a

View its output:

container logs my-web-server

Execute a command inside the running container:

container exec my-web-server ls /app

Resource Configuration

Default resources for containers are 1 GB RAM and 4 CPUs. Override them:

container run --name my-app --memory 2g --cpus 2 my-image

The builder runs with 2 GB RAM and 2 CPUs by default. Configure it:

container builder start --memory 4g --cpus 4

Port Publishing

Expose a container port to the host:

container run --name web-app -p 8080:80 my-image

Now open http://localhost:8080 in a browser.

Volume Mounting

Mount a local directory into the container:

container run --name dev-env -v /Users/me/project:/workspace my-image

Useful Commands

Command	What it does
`container ls`	List running containers
`container ls -a`	List all containers
`container stop my-app`	Stop a container
`container exec my-app cmd`	Run a command inside a container
`container logs my-app`	Fetch container logs
`container stats my-app`	View resource usage
`container image tag src dest`	Tag an image
`container image push image`	Push to a registry

Abbreviations work: ls for list, rm for delete, -a for --all.

Shell completion is available for zsh, bash, and fish.

Summary

In this post, I walked through installing Apple container, starting the service, building an image from a Dockerfile, running a container, and managing it with the CLI. The commands are familiar to anyone who has used Docker, but the underlying architecture gives each container its own dedicated VM.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Apple container GitHub Releases
👨‍💻 Apple container README

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!