> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
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](https://podman.io/get-started/).
* 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:
1. Run the following command to identify the connection URI for `podman-machine-default`:
```sh wrap theme={null}
podman system connection ls
```
The output should look like the following:
```text wrap theme={null}
podman-machine-default* /Users/user/.ssh/podman-machine-default ssh://core@localhost:54523/run/user/1000/podman/podman.sock
podman-machine-default-root /Users/user/.ssh/podman-machine-default ssh://root@localhost:54523/run/podman/podman.sock
```
2. Copy the value in the `URI` column from `podman-machine-default*`. This is typically `unix:///run/podman/podman.sock`, but it can vary based on your installation.
3. Set your `DOCKER_HOST` environment variable to the value of the URI.
### Setup
1. Run the following command to confirm that Podman has access to Astro images at `docker.io`:
```sh wrap theme={null}
podman run --rm -it postgres:12.6 whoami
```
If this command fails, use [Podman Desktop](https://podman-desktop.io/) to change Podman's default image registry location to `docker.io`. See [Provide pre-defined registries](https://podman-desktop.io/blog/podman-desktop-release-0.11#provide-pre-defined-registries-1201).
Set up Podman on Windows so you can run Apache Airflow locally and deploy to Astro with Podman containers.
### Prerequisites
* Podman 3 or later installed on Windows Subsystem for Linux version 2 (WSL 2) using Ubuntu 22.04 or later. See [Install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install) and [Getting started with Podman](https://podman.io/get-started/).
* A running Podman machine with at least 4 GiB of RAM. To confirm that Podman is running, run `podman ps` in your Linux terminal.
* The Astro CLI Linux distribution installed on WSL 2. See [Install the Astro CLI on Linux](/docs/cli/v1.38/install-cli#linux).
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:
1. In a WSL 2 terminal, run the following command to identify the connection URI for `podman-machine-default`:
```sh wrap theme={null}
podman system connection ls
```
The output should look like the following:
```text wrap theme={null}
podman-machine-default* /Users/user/.ssh/podman-machine-default ssh://core@localhost:54523/run/user/1000/podman/podman.sock
podman-machine-default-root /Users/user/.ssh/podman-machine-default ssh://root@localhost:54523/run/podman/podman.sock
```
2. Copy the value in the `URI` column from `podman-machine-default*`. This is typically `unix:///run/podman/podman.sock`, but it can vary based on your installation.
3. Set your `DOCKER_HOST` environment variable to the value of the URI.
### Setup
1. In a WSL 2 terminal, run the following command to confirm that Podman has access to Astro images at `docker.io`:
```sh wrap theme={null}
podman run --rm -it postgres:12.6 whoami
```
If this command fails, run the following command to change Podman's default image registry location to `docker.io`:
```sh wrap theme={null}
cat << EOF | sudo tee -a /etc/containers/registries.conf.d/shortnames.conf
"postgres" = "docker.io/postgres"
EOF
```
Set up Podman on Linux so you can run Apache Airflow locally and deploy to Astro with Podman containers.
### Prerequisites
* Podman 3 or later. See [Getting started with Podman](https://podman.io/get-started/).
* 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:
1. Run the following command to identify the connection URI for `podman-machine-default`:
```sh wrap theme={null}
podman system connection ls
```
The output should look like the following:
```text wrap theme={null}
podman-machine-default* /Users/user/.ssh/podman-machine-default ssh://core@localhost:54523/run/user/1000/podman/podman.sock
podman-machine-default-root /Users/user/.ssh/podman-machine-default ssh://root@localhost:54523/run/podman/podman.sock
```
2. Copy the value in the `URI` column from `podman-machine-default*`. This is typically `unix:///run/podman/podman.sock`, but it can vary based on your installation.
3. Set your `DOCKER_HOST` environment variable to the value of the URI.
### Setup
1. Run the following command to confirm that Podman has access to Astro images at `docker.io`:
```sh wrap theme={null}
podman run --rm -it postgres:12.6 whoami
```
If this command fails, run the following command to change Podman's default image registry location to `docker.io`:
```sh wrap theme={null}
cat << EOF | sudo tee -a /etc/containers/registries.conf.d/shortnames.conf
"postgres" = "docker.io/postgres"
EOF
```
Run the following command to set Podman as your container management engine for the Astro CLI:
```sh wrap theme={null}
astro config set -g container.binary podman
```
If you're using Podman 3, additionally run the following command:
```sh wrap theme={null}
astro config set -g duplicate_volumes false
```
## Troubleshooting
#### SHELL is not supported for OCI image format
```bash wrap theme={null}
WARN[0010] SHELL is not supported for OCI image format, [/bin/bash -o pipefail -e -u -x -c] will be ignored. Must use `docker` 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:
```bash wrap theme={null}
export BUILDAH_FORMAT=docker
```
#### Cannot connect to the Docker daemon
```bash wrap theme={null}
Error: error creating docker-compose project: Cannot connect to the Docker daemon at unix:///Users/[YOUR.USER]/.docker/run/docker.sock. Is the docker daemon running?
```
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
```bash wrap theme={null}
Error: error reading credentials: error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH, out: ``
```
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](https://forums.docker.com/t/docker-credential-desktop-exe-executable-file-not-found-in-path-using-wsl2/100225).