Skip to content

Instantly share code, notes, and snippets.

Last active July 13, 2024 06:05
Show Gist options
  • Save acdha/9be1c3521af4f18d9f86264a889581e2 to your computer and use it in GitHub Desktop.
Save acdha/9be1c3521af4f18d9f86264a889581e2 to your computer and use it in GitHub Desktop.
Instructions for using Podman as a replacement on MacOS

Podman as a Docker Desktop alternative


  1. Install Homebrew from

Install Podman

$ brew install podman
$ podman machine init # optionally configure memory / CPU / disk sizes

If you want to share your host filesystem with the guest VM, provide the -v option to set the host path and the location where it should be mapped to. For convenience, I use the same path in both cases to avoid needing to remember that mapping on every podman run command:

$ podman machine init -v $(realpath ~/Projects):$(realpath ~/Projects)

Using Podman

When you want to run containers, start the VM which Podman will use to run them:

$ podman machine start

The podman CLI is mostly compatible with the docker CLI. You can either retrain your memory or add an alias to your shell configuration:

$ alias docker podman

Docker Compose

As of 3.x, podman works with Compose. See e.g. for a tutorial.

If you run into problems with compose builds failing with this error it's because of compatibility issues with BuildKit which are in the process of being resolved. You can avoid those by setting DOCKER_BUILDKIT=0 in your environment:

$ docker-compose create
[+] Building 0.0s (0/0)                                                                                                                
listing workers for Build: failed to list workers: Unavailable: connection error: desc = "transport: Error while dialing unable to upgrade to h2c, received 404"
$ DOCKER_BUILDKIT=0 docker-compose up
Sending build context to Docker daemon  2.723GB
STEP 1/16: FROM amazonlinux:2

Legacy networking

Podman does not support the legacy Docker network linking feature (docker run --link) which has been deprecated by Docker as well. You can replace this with the new network calls (podman network create, etc.) and replacing --link with --network in your invocations, which is a good move for the future when the deprecated functionality is removed from dockerd.

Apple Silicon and AMD-64 x86 container images

Thanks to a recently-landed QEMU patch, ARM64 containers work seamlessly. If you want to run x86 containers, the multiarch qemu-user-static package will need a one-time install:

$ podman machine ssh podman-machine-default sudo rpm-ostree install qemu-user-static
$ podman machine ssh podman-machine-default sudo systemctl reboot
Copy link

Background information from RedHat's Brent Baude

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment