> ## 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

> Configure the Astro CLI to use Podman as its container management engine for running Airflow locally and deploying to Astro.

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

<Tabs>
  <Tab title="Mac">
    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`.

    <Tip>
      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.
    </Tip>

    ### 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).
  </Tab>

  <Tab title="WSL2 on Windows">
    Set up Podman on Windows so you can run Apache Airflow locally and deploy to Astro with Podman containers. This setup runs both Podman and the Astro CLI inside WSL 2. If you installed the Astro CLI with winget, Podman is already installed on Windows and you run `astro` commands in PowerShell. See [Install the Astro CLI](/docs/cli/v1.44/install-cli?tab=windows-winget).

    ### 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.44/install-cli#linux).

    <Tip>
      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.
    </Tip>

    ### 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
       ```
  </Tab>

  <Tab title="Linux">
    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`.

    <Tip>
      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.
    </Tip>

    ### 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
       ```
  </Tab>
</Tabs>

<Accordion title="For CLI versions 1.30.0 and earlier">
  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
  ```
</Accordion>

## 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).