Skip to main content

How to replace Docker with Podman on a Mac

Want to use Podman to work with containers? Here's what you need to know about Podman on a Mac.
How to replace Docker with Podman on MacOS
Image by Magnascan from Pixabay

Back in March 2021, I wrote about how I replaced Docker with Podman on a Mac using VirtualBox and Vagrant after an old version of podman machine became deprecated. That very same month, a new version of podman machine was released, which pretty much rendered my article obsolete and caused a bit of confusion.

Using the podman machine command's functionality is so much easier now, as Brent Baude explains in How Podman runs on Macs and other container FAQs. As I was moving from my VirtualBox/Vagrant setup, I wanted to revisit this topic in case your design is similar to mine. Here are some tips I found when moving over to podman machine; hopefully, by sharing them I will help some folks out!

From Vagrant to podman machine

I am going to assume you installed podman using Homebrew. The first thing to do is to get the latest version of Podman by running:

$ brew upgrade podman

If you are anything like me and want results fast, go ahead and run these commands after the upgrade:

$ podman machine init
$ podman machine start

When I ran this, the init command worked like a charm, but the start command wasn't happy and told me so:

Error: unable to start host networking: "could not find \"gvproxy\" in one of [/usr/local/opt/podman/libexec /opt/homebrew/bin /opt/homebrew/opt/podman/libexec /usr/local/bin /usr/local/libexec/podman /usr/local/lib/podman /usr/libexec/podman /usr/lib/podman]"

After a couple of internet searches, I found a recommendation to add the following line to the ~/.config/containers/containers.conf file:


NOTE: This is a fairly recent issue, and it may be resolved in newer Podman releases. As you can see, I'm using 3.4.1. This version definitely solved the gvproxy error, but here's where my Vagrant setup tripped me up. I reran the podman machine start command, but it still was not happy, saying it was unable to connect due to a failed sshClient error. I decided to look at my old Vagrant connection by running:

$ podman system connection list

I noticed the Vagrant connection still existed as the default connection. I quickly changed the default and removed the Vagrant connection, but I still got the same error. So, I ran the following command to get more debug information:

$ podman --log-level=debug ps
INFO[0000] podman filtering at log level debug
DEBU[0000] Called ps.PersistentPreRunE(podman --log-level=debug ps)
DEBU[0000] SSH Ident Key "/Users/dmeurer/Dev/images/podman/.vagrant/machines/default/virtualbox/private_key" SHA256:EhLJssA0acBO7LQVx8UrHzQPeVXB2gwn+a+wXdOaCKY ssh-rsa
DEBU[0000] Found SSH_AUTH_SOCK "/private/tmp/", ssh-agent signer(s) enabled
Cannot connect to Podman. Please verify your connection to the Linux system using `podman system connection list`, or try `podman machine init` and `podman machine start` to manage a new Linux VM

Error: unable to connect to Podman. failed to create sshClient: Connection to bastion host (ssh://vagrant@ failed.: dial tcp connect: connection refused

Since I can't remember what I had for breakfast today, let alone something I did months ago, I went back to my previous article to see if anything I did might force Podman to use that Vagrant private key. Well, sure enough, there it was in step 6! Global variables were still telling Podman to use the Vagrant SSH key setup. All I needed to do was to nuke the CONTAINER_HOST and CONTAINER_SSHKEY lines from my ~/.zshrc file, and podman machine start worked as advertised.

Make it a macOS app

Now that podman machine was working great on my Mac, I wanted to be sure the Seals macOS app I used in the previous article worked. In that article, I created a Bash shell script called pman to start and stop my VirtualBox and Vagrant setup quickly, and I created an application named Seals to make the script easier to run. The new pman script needed a couple of tweaks to use podman machine:



case $ACTION in
    echo "Shutting down podman machine"
    podman machine stop

    echo "STARTING podman machine"
    podman machine start

    echo "CREATING a new podman machine"
    podman machine init

I then tried my Seals macOS app, and I got an interesting podman not found error. So, I opened up Automator on my Mac, chose Open an Existing Document..., and opened up the Seals app.

[ Learn more about the Red Hat OpenShift Container Platform. ] 

You may not need to do this depending upon where your Podman executable is located. I created a Podman symlink in a local bin directory, so I had to play around with the first export line to ensure it found my Podman executable.

modifications of the Seals app
Modifying the Seals application to find the Podman executable. (Dave Muerer, CC BY-SA 4.0)

You'll need to update the paths in the screenshot above to where you saved and named the Bash script. Once I got the path right, my Seals app worked great.

    Seals Info window
    The Get Info window for Seals. (Dave Muerer, CC BY-SA 4.0)

    In case you are wondering how I attached the Podman logo to my macOS app, here is the process. I found the Podman logo and created a 128x128 PNG image with GIMP to use as the Application icon with these steps:

    1. Open the 128x128 PNG in preview and click Edit > Copy.
    2. Right-click the new application, and click Get Info.
    3. Select the icon on the top left, and paste the contents of the clipboard.

    Now you can use Alfred or Spotlight to quickly launch Podman and free up precious milliseconds of your workday to focus on the things that matter… like an early lunch!

    Searching for Seals with Alfred
    Searching for Seals with Alfred. (Dave Muerer, CC BY-SA 4.0)


    I hope this will help those folks who are either looking for an easy way to launch Podman on macOS or are using a Vagrant setup similar to the one I documented. The main reason I revisited this topic was that Podman updates made my previous article obsolete, and it is so much easier now to use Podman on a macOS because of podman machine. You no longer need VirtualBox and Vagrant, just Podman! Happy containerizing!

    Editor's note: This article was originally published in March 2021 and has been updated.

    Topics:   Linux   Containers   Podman  
    Author’s photo

    Dave Meurer

    Dave Meurer currently serves as a Principal Solution Architect on the Red Hat Global Partner Security ISV team, where he owns technical relationships and evangelism with security independent software vendor partners of Red Hat. More about me

    Try Red Hat Enterprise Linux

    Download it at no charge from the Red Hat Developer program.