Install Podman on MacOS

Summary

Docker on Apple Silicon is a bit cumbersome to install these days without the use of Docker Desktop. With the licence change of Docker Desktop, it is now only permitted if a valid licence is procured. Podman is an open-source alternative to Docker, which seems to be mature enough to run containers on MacOS with stability

WWDC 2025 revealed an interesting project from Apple themselves simply called container. This is very much in its infancy, but may prove valuable in the future. For the time being, we will be sticking with Podman

Note, this is not Podman Desktop. Rather, this is the Podman CLI. We will also use this to run docker as the frontend with podman acting as the backend. This will allow us to run docker compose as well as docker buildx

Note

A small aside:

Podman is not a CRI compliant runtime like CRI-O and containerd. Tools like kind will let you run Kubernetes clusters in Podman, with Kind nodes hosted as containers in Podman

nerdctl is an interesting project whose goal is to make containerd behave like Docker. It's out of scope here, but something that some may want to look into

Useful article on the topic (not my own work):

podman vs. nerdctl: What’s the Deal?

Installation instructions

1. Install Podman via brew

   brew install podman

2. Install the podman-mac-helper. This will redirect /var/run/docker.sock to Podman

   sudo podman-mac-helper install

3. Install Docker CLI (Note, this will not install the Docker engine. We will be using Podman as the backend for this)

   brew install docker

4. Create a Podman machine (this is a Linux virtual machine created on MacOS which Podman will run in). See https://docs.podman.io/en/latest/markdown/podman-machine-init.1.html for list of flags. You may want to increase number of CPUS or Memory

   podman machine init
   
   # To add extra memory to the Podman machine, add the `memory` flag
   # Note, the value here is MB and not MiB
   podman machine set --memory 4000

5. Start the Podman VM

   podman machine start

6. Test if Podman works (You should see the Podman logo hopefully)

   podman run hello-world

7. Try and run an image using Docker

   docker run docker.io/library/hello-world

   [!NOTE] This image is coming from DockerHub. The previous step will have come from Quay.io as this is the default registry in Podman if no registry is given. This is different to Docker, where DockerHub is the default. This can be changed within Podman should an alternative default registry be favourable

8. Install the Docker Compose plugin

   brew install docker-compose

9. Create (or edit) ~/.docker/config.json and add the following:

    {
      "cliPluginsExtraDirs": [
      "/opt/homebrew/lib/docker/cli-plugins"
      ]
    }

   [!TIP] This is also noted in the instructions when installing docker-compose via brew as well as the Homebrew formula page for Docker Compose

10. Check the Docker compose plugin is installed

    docker compose version

    [!IMPORTANT] This is the v2 docker compose project written in Go. Not to be confused with the legacy v1 docker-compose project that was written in Python. I.e. all commands are docker compose and not docker-compose with the version of docker compose we have just installed

    See the Docker Compose migration docs for details