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.

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.

Install the Astro CLI

Mac
Windows with winget
Windows (Manual)
Linux

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

Prerequisites

Homebrew.
A container service like Docker Desktop (v18.09 or higher) or Podman.

By default, the Astro CLI uses Docker as its container management engine for running Airflow locally. However, if your organization uses Podman to run and manage containers, you can configure the Astro CLI to use it instead. See Run the Astro CLI with Podman for prerequisites and configuration steps.

Installation

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

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

brew install astro@1.31.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.

Confirmation

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

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):
```
brew update
```
Re-run the installation again:
```
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:
```
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:
```
brew install astro
```

Starting with Astro CLI version 1.6, 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 alternate Windows installation process.

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. If you've installed the App Installer previously, make sure you're using the latest version before running commands.

Prerequisites

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.
A container service, like Docker Desktop (v18.09 or higher) or Podman.

Installation

Open Windows PowerShell as an administrator and then run the following command:
```
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:
```
winget install -e --id Astronomer.Astro -v 1.31.0
```
Run astro version to confirm the Astro CLI is installed properly.

Resolve installation issues

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

Manually installing the Astro CLI to Windows is recommended only if you're upgrading from Astro CLI version 1.5.1 or earlier to version 1.6.0 or later. Starting with Astro CLI version 1.6.0, Astronomer recommends using Windows Package Manager winget command-line tool to install the Astro CLI. See Windows with winget.

Prerequisites

Microsoft Hyper-V enabled. See Install Hyper-V On Windows or Step-By-Step: Enabling Hyper-V on Windows 11.
Windows 10 or Windows 11.
A container service like Docker Desktop or Podman.

By default, the Astro CLI uses Docker as its container management engine. However, if your organization uses Podman to run and manage containers, you can configure the Astro CLI to use it instead. See Run the Astro CLI with Podman for prerequisites and configuration steps.

Installation

Go to the Releases page 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.
Rename the file to astro.exe.
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?.
Restart your machine.

Prerequisites

A container service like Docker Desktop (v18.09 or higher) or Podman.

Installation

Run the following command to install the latest version of the Astro CLI directly to PATH:

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:

curl -sSL install.astronomer.io | sudo bash -s -- v1.31.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.

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:

brew upgrade astro

Starting with Astro CLI version 1.6, you can use the winget command line tool to upgrade the Astro CLI. To upgrade the Astro CLI to the latest version, open Windows PowerShell as an administrator and run the following command:

winget install -e --id Astronomer.Astro

Note that if you're upgrading from Astro CLI version 1.5.1 or earlier to a later Astro CLI version, you still need to install the upgrade version manually.

Delete the existing astro.exe file on your machine.
Go to the Releases page 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 upgrade to v1.0.0 of the Astro CLI on a Windows machine with an AMD 64 architecture, you download astro_1.0.0-converged_windows_amd64.exe.
Rename the file to astro.exe.
Add the filepath for the directory containing the new astro.exe as a PATH environment variable. For example, if astro.exe was stored in C:\Users\username\astro.exe, you would add C:\Users\username as your PATH environment variable. To learn more about configuring the PATH environment variable, see Java documentation.
Restart your machine.

To upgrade the Astro CLI to the latest version, run the following command:

curl -sSL install.astronomer.io | sudo bash -s

Uninstall the Astro CLI

Mac
Windows with winget
Windows (Manual)
Linux

To uninstall the Astro CLI on Mac, run:

brew uninstall astro

Starting with Astro CLI version 1.6, you can use the winget command line tool to uninstall the Astro CLI. To uninstall an older version of the Astro CLI, you'll need to follow the alternate Windows uninstall process.

To uninstall the Astro CLI, open Windows PowerShell as an administrator and run the following command:

winget uninstall -e --id Astronomer.Astro

To uninstall the Astro CLI on Windows:

Delete the filepath for astro.exe from your Windows PATH environment variable.
Delete astro.exe.

Run the following command to uninstall the Astro CLI on Linux:

sudo rm /usr/local/bin/astro