Install the Astro CLI

This document explains all of the possible 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.

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.

Mac

Windows with winget

Windows (Manual)

Linux

Install the Astro CLI on Mac OS with a single command.

Prerequisites

Homebrew.

Starting with version 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, install from our tap with brew install astronomer/tap/astro --without-podman.

Installation

To install the latest version of the Astro CLI, run the following command:

1 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.35.1, you would run the following command:

1 brew install astro@1.35.1

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.

Confirmation

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

1 astro version

Resolve installation issues

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 in the Homebrew documentation.

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

1 brew update

Re-run the installation again:

1 brew install astro

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:
```
1 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 in the Homebrew documentation.

Run the following command to install the Astronomer CLI:

1 brew install astro

Upgrade the Astro CLI

The Astro CLI contains no breaking changes between minor versions within the same major version. Therefore, Astronomer recommends always using the latest minor version of the Astro CLI with in your major version.

Mac

Windows with winget

Windows (Manual)

Linux

Run the following command to upgrade the Astro CLI to the latest version:

1 brew upgrade astro

Uninstall the Astro CLI

Mac

Windows with winget

Windows (Manual)

Linux

To uninstall the Astro CLI on Mac, run:

1 brew uninstall astro

Container management engine

The Astro CLI automatically runs Podman containers whenever you run a command that requires them. You can switch between Podman and Docker as your container management engine to run Astro CLI commands.

Prerequisites

Docker

Podman

Microsoft Hyper-V enabled. See Install Hyper-V On Windows or Step-By-Step: Enabling Hyper-V on Windows 11.
The latest version of the Windows App Installer.
Windows 10 1709 (build 16299) or later or Windows 11.

Switch between Podman and Docker

To run CLI commands in Docker containers, run the following command:

1 astro config set container.binary docker -g

If you need to switch back to using Podman again, run the following command:

1 astro config set container.binary podman -g

If you want to switch betwen Docker and Podman on a specific project without changing the global configuration, run these commands without the -g.