Skip to main content

Troubleshooting Podman on macOS

Unable to set custom binary path for Podman on macOS​

Issue​

When setting a custom binary path (under Preferences -> Custom binary path), Podman is unable to find gvproxy and podman-mac-helper:

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 $BINDIR/../libexec/podman].  To resolve this error, set the helper_binaries_dir key in the `[engine]` section of containers.conf to the directory containing your helper binaries."

Solution​

  1. Download gvproxy from the gvisor-tap-vsock release page.
  2. Build the podman-mac-helper from the source code on the Podman GitHub page.
  3. Add the helpers_binaries_dir entry to ~/.config/containers/conf:
[containers]

helper_binaries_dir=["/Users/user/example_directory"]

NOTE: A pre-built binary will be added to the Podman release page so you do not have to build podman-mac-helper. An issue is open for this.

Unable to locate Podman Engine​

Issue​

Despite having Podman Engine installed, you might receive an error as follows - Error: No such keg: /usr/local/Cellar/podman or any similar error denoting that Podman Engine does not exist.

Explanation​

The Podman Installer and Homebrew use different locations to store the Podman Engine files in the file system. For example, Podman Installer installs Podman Engine in the path /opt/podman whereas Homebrew uses the path /usr/local for macOS Intel, /opt/homebrew for Apple Silicon and /home/linuxbrew/.linuxbrew for Linux.

Solution​

To check where exactly is your Podman Engine installed, run the command-

which podman

This returns the path where the Podman Engine would be installed. This would help determine further action.

For example, if you’re looking to completely uninstall Podman Engine from your system for a fresh installation, running which podman returns the exact path where Podman still exists. This could be the path where Podman Installer stores Podman Engine, such as /opt/podman. Once you know the path, run:

sudo rm -rf /opt/podman

Or

sudo rm -rf path-where-podman-exists

Here, you would replace path-where-podman-exists with the output of which podman.

You can now proceed for a fresh installation of Podman Desktop

Podman machine on Apple Silicon​

Issue​

If you are using an Apple Silicon and brew, you might encounter the following error when starting Podman from Podman Desktop

Error: qemu exited unexpectedly with exit code 1, stderr: qemu-system-x86_64: invalid accelerator hvf
qemu-system-x86_64: falling back to tcg
qemu-system-x86_64: unable to find CPU model 'host'

Explanation​

Podman machine is running as a x86_64 process and it could be due to a dual install of homebrew: one for x86_64 and one for arm64.

Solution​

You can

  1. Uninstall Podman machine on your x86_64 brew install (for example from a terminal running under rosetta) brew uninstall podman
  2. or uninstall brew x86_64 as most brew receipe have now arm64 support: follow these instructions from a terminal running under rosetta

Then run a terminal in native mode (default) and install Podman machine brew install podman

Finally clean the Podman machine VMs that had been previously created, and create new ones.

$ podman machine rm podman-machine-default
$ podman machine init

You should be a happy camper from here.

Recovering from a failed start​

After a failed start, the Podman machine might be unable to start because a QEMU process is still running and the PID file is in use.

Workaround​

  1. Kill the remaining QEMU process and stop the Podman machine:

    $ ps -edf | grep qemu-system | grep -v grep | awk '{print $2}' | xargs -I{} kill -9 {}; podman machine stop

  2. Start the Podman machine.

Solution​

Use Podman 4.6.1 or greater.

Podman machine not starting with QEMU 8.1.0 from brew​

When you installed Podman and QEMU with brew, and QEMU version is 8.1.0, Podman machine might fail to start with an error such as: Error: qemu exited unexpectedly with exit code -1, stderr: qemu-system-x86_64: Error: HV_DENIED

Solution​

Workaround​

Keep your brew-based installation and apply one of these workarounds:

  • Rollback the QEMU brew package to v8.0.3.

    $ brew uninstall qemu
    $ curl -OSL https://raw.githubusercontent.com/Homebrew/homebrew-core/dc0669eca9479e9eeb495397ba3a7480aaa45c2e/Formula/qemu.rb
    $ brew install ./qemu.rb

  • Alternatively, sign the QEMU brew binary locally:

    $ cat >entitlements.xml <<EOF
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
      <key>com.apple.security.hypervisor</key>
      <true/>
    </dict>
    </plist>
    EOF
    $ codesign --sign - --entitlements entitlements.xml --force /usr/local/bin/qemu-system-$(uname -m | sed -e s/arm64/aarch64/)

Additional resources​