Podman for the Astro CLI
The Astro CLI requires a container management engine to run Apache Airflow components on your local machine and deploy to Astro. For example, the astro dev start
and astro deploy
commands both require containers.
Starting with version 1.32.0, the Astro CLI is packaged with Podman as its container management engine for running Airflow locally, when installed by Homebrew or Winget.
Configure the Astro CLI to use Podman
Mac
WSL2 on Windows
Linux
Set up Podman on a Mac operating system so you can run Apache Airflow locally and deploy to Astro with Podman containers.
Prerequisites
- Podman 3 or later. See Getting started with Podman.
- A running Podman machine with at least 4 GiB of RAM. To confirm that Podman is running, run
podman ps
.
If you receive an error after running podman ps
, there is likely a problem with your Podman connection. You might need to set the system-level DOCKER_HOST
environment variable to be the location of your Podman service socket:
-
Run the following command to identify the connection URI for
podman-machine-default
:The output should look like the following:
-
Copy the value in the
URI
column frompodman-machine-default*
. This is typicallyunix:///run/podman/podman.sock
, but it can vary based on your installation. -
Set your
DOCKER_HOST
environment variable to the value of the URI.
Setup
-
Run the following command to confirm that Podman has access to Astro images at
docker.io
:If this command fails, use Podman Desktop to change Podman’s default image registry location to
docker.io
. See Provide pre-defined registries.
For CLI versions 1.30.0 and earlier
Run the following command to set Podman as your container management engine for the Astro CLI:
If you’re using Podman 3, additionally run the following command:
Troubleshooting
SHELL is not supported for OCI image format
This error can occur when the CLI tries to build your Astro Runtime image using Podman.
To resolve this issue, run the following command to set the BUILDAH_FORMAT
environment variable on your machine:
Cannot connect to the Docker daemon
Ensure Docker Compatibility is enabled in Settings > Preferences > Experimental (Docker Compatibility) and Docker CLI Context is set to unix://var/run/docker.sock
.
”docker-credential-desktop”: executable file not found
This error can occur when Docker used to be installed, but no longer exists on the system. When podman runs, it is checking $HOME/.docker/config.json
for registered credentials stores.
To resolve the issue, delete the corresponding Docker configuration at $HOME/.docker
from the system or install Docker again.
Further info can be found here.