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

# Install the Astro CLI

There are multiple ways to install, upgrade, and uninstall the Astro CLI. Install the Astro CLI to start running Airflow locally or to manage Astro from your terminal.

<Info>If you can't install the Astro CLI on your local machine, you can still run Astro CLI commands and deploy to Astro using [GitHub Actions](/docs/astro/first-dag-github-actions).</Info>

## Prerequisites

<Tabs>
  <Tab title="Mac" language="mac">
    * [Homebrew](https://brew.sh/).

    Starting with version 1.32.0, the Astro CLI Homebrew tap installs Podman by default on macOS to run Airflow locally. If your organization uses Docker and you want to skip installing Podman, install from the Astronomer tap and pass `--without-podman` (macOS only):

    ```sh wrap theme={null}
    brew tap astronomer/tap
    brew install astronomer/tap/astro --without-podman
    ```

    <Note>`brew install astro` (Homebrew core) does not support `--without-podman` and will install Podman.</Note>
  </Tab>

  <Tab title="Windows with winget" language="windows-winget">
    * (Optional) The winget command line tool is supported on Windows 10 1709 (build 16299) or later, and is bundled with Windows 11 and modern versions of Windows 10 by default as the App Installer. If you're running an earlier version of Windows 10 and you don't have the App Installer installed, you can download it from the [Microsoft Store](https://apps.microsoft.com/store/detail/app-installer/9NBLGGH4NNS1?hl=en-ca\&gl=ca). If you've installed the App Installer previously, make sure you're using the latest version before running commands.

    * Windows Subsystem for Linux (WSL) 2 enabled: See [Enable the Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install), [WSL basic commands](https://learn.microsoft.com/en-us/windows/wsl/basic-commands), and [Troubleshooting WSL 2](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#error-0x80370102-the-virtual-machine-could-not-be-started-because-a-required-feature-is-not-installed).
      * After you enable WSL, run:
      ```text wrap theme={null}
       wsl --update
       wsl --install --no-distribution
      ```

    * The latest version of the Windows [App Installer](https://apps.microsoft.com/store/detail/app-installer/9NBLGGH4NNS1?hl=en-ca\&gl=ca).

    * Windows 10 1709 (build 16299) or later or Windows 11.

    Starting with 1.32.0, the Astro CLI installs Podman, by default, as its container management engine for running Airflow locally. If your organization uses Docker to run and manage containers, you can opt out of installing Podman with the Astro CLI, allowing the Astro CLI to use your existing runtime setup. To opt out, use `winget install -e --id Astronomer.Astro --skip-dependencies`.
  </Tab>

  <Tab title="Windows (Manual)" language="windows-manual">
    * Windows Subsystem for Linux (WSL) 2 enabled: See [Enable the Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install), [WSL basic commands](https://learn.microsoft.com/en-us/windows/wsl/basic-commands), and [Troubleshooting WSL 2](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#error-0x80370102-the-virtual-machine-could-not-be-started-because-a-required-feature-is-not-installed).
      * After you enable WSL, run:
      ```text wrap theme={null}
       wsl --update
       wsl --install --no-distribution
      ```
    * Windows 10 or Windows 11.
    * A container service like [Podman](https://podman.io/docs/installation) or [Docker Engine](https://docs.docker.com/engine/install/).
  </Tab>

  <Tab title="Linux" language="linux">
    * A container service like [Podman](https://podman.io/docs/installation) or [Docker Engine](https://docs.docker.com/engine/install/).
  </Tab>
</Tabs>

## Installation

<Tabs>
  <Tab title="Mac" language="mac">
    To install the latest version of the Astro CLI, run the following command:

    ```sh wrap theme={null}
    brew install astro
    ```

    To install a specific version of the Astro CLI, specify the version you want to install at the end of the command. For example, to install Astro CLI version 1.36.0, you would run the following command:

    ```sh wrap theme={null}
    brew install astro@1.36.0
    ```

    If you specify only a major version, this command installs the latest minor or patch version available for the major version. For a list of all available versions, see the [CLI release notes](/docs/cli/v1.41/release-notes).

    To verify that the correct Astro CLI version was installed, run:

    ```sh wrap theme={null}
    astro version
    ```
  </Tab>

  <Tab title="Windows with winget" language="windows-winget">
    <Warning>
      You can use the Windows Package Manager winget command-line tool to install the Astro CLI. To install an older version of the Astro CLI, you'll need to follow the Manual Windows installation process.
    </Warning>

    1. Open Windows PowerShell as an administrator and then run the following command:

       ```sh wrap theme={null}
       winget install -e --id Astronomer.Astro
       ```

       To install a specific version of the Astro CLI, specify the version you want to install at the end of the command. For example, running the following command specifies the latest available version of the Astro CLI:

       ```sh wrap theme={null}
       winget install -e --id Astronomer.Astro -v 1.36.0
       ```

    2. Run `astro version` to confirm the Astro CLI is installed properly.
  </Tab>

  <Tab title="Windows (Manual)" language="windows-manual">
    <Warning>
      Astronomer recommends using the Windows Package Manager winget command-line tool to install the Astro CLI.
    </Warning>

    1. Go to the [Releases page](https://github.com/astronomer/astro-cli/releases) of the Astro CLI GitHub repository, scroll to a CLI version, and then download the `.exe` file that matches the CPU architecture of your machine.

       For example, to install v1.18.2 of the Astro CLI on a Windows machine with an AMD 64 architecture, download `astro_1.18.2_windows_amd64.exe`.

    2. Rename the file to `astro.exe`.

    3. Add the filepath for the directory containing the new `astro.exe` as a PATH environment variable. For example, if `astro.exe` is stored in `C:\Users\username\astro.exe`, you add `C:\Users\username` as your PATH environment variable. To learn more about configuring the PATH environment variable, see [How do I set or change the PATH system variable?](https://www.java.com/en/download/help/path.html).

    4. Restart your machine.
  </Tab>

  <Tab title="Linux" language="linux">
    Run the following command to install the latest version of the Astro CLI directly to `PATH`:

    ```sh wrap theme={null}
    curl -sSL install.astronomer.io | sudo bash -s
    ```

    To install a specific version of the CLI, specify the version number as a flag at the end of the command. For example, to install the most recent release of the CLI, you would run:

    ```sh wrap theme={null}
    curl -sSL install.astronomer.io | sudo bash -s -- v1.36.0
    ```

    If you specify only a major version, this command installs the latest minor or patch version available for the major version. If you specify only a major version, this command installs the latest minor or patch version available for the major version. For a list of all available versions, see the [CLI release notes](/docs/cli/v1.41/release-notes).
  </Tab>
</Tabs>

## Resolve installation issues

<Tabs>
  <Tab title="Mac" language="mac">
    Follow this procedure when Homebrew fails to install the latest Astro CLI version or the error `No formulae or casks found for astro@<major.minor.patch-version>` appears. To troubleshoot other Homebrew issues, see [Common Issues](https://docs.brew.sh/Common-Issues) in the Homebrew documentation.

    1. If the install process is not working, run the following command to update Homebrew and all package definitions (formulae):

       ```sh wrap theme={null}
       brew update
       ```

    2. Re-run the installation again:

       ```sh wrap theme={null}
       brew install astro
       ```

    3. If this is the first time you're installing the CLI and updating Homebrew doesn't work, check to see if `astronomer/tap` is in your [Homebrew tap list](https://docs.brew.sh/Taps):

       ```sh wrap theme={null}
       brew tap astronomer/tap
       ```

       If `astronomer/tap` is in your tap list and you still can't install the Astro CLI, you might be experiencing a different issue. See [Common Issues](https://docs.brew.sh/Common-Issues) in the Homebrew documentation.

    4. Run the following command to install the Astronomer CLI:

       ```sh wrap theme={null}
       brew install astro
       ```

    ### Troubleshooting `--without-podman`

    #### Error: No available formula or cask with the name "astronomer/tap/astro"

    Run `brew tap astronomer/tap`, then retry the install.

    #### Error: invalid option: `--without-podman`

    You're installing the Homebrew core formula. Use the fully qualified tap formula:

    ```sh wrap theme={null}
    brew install astronomer/tap/astro --without-podman
    ```

    #### Already installed core formula

    Uninstall it, then reinstall from the tap:

    ```sh wrap theme={null}
    brew uninstall astro
    brew install astronomer/tap/astro --without-podman
    ```
  </Tab>

  <Tab title="Windows with winget" language="windows-winget">
    If an error message appears indicating that the term winget is not recognized as an internal or external command when you attempt to run winget commands, see this [troubleshooting document](https://github.com/microsoft/winget-cli/tree/master/doc/troubleshooting#common-issues) provided by Microsoft.

    If you're still struggling to install the Astro CLI with winget, retry the install using the alternative instructions in [Windows (Manual)](/docs/cli/v1.41/install-cli?tab=windows-manual#installation).
  </Tab>
</Tabs>