Install the Astro CLI

Instructions for installing, upgrading, and uninstalling the Astro command-line interface (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.

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

.

Prerequisites

Mac

• Homebrew.

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

brew tap astronomer/tap
brew install astronomer/tap/astro --without-podman

brew install astro

(Homebrew core) does not support

--without-podman

and will install Podman.

Windows with 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. 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, WSL basic commands, and Troubleshooting WSL 2.

  • After you enable WSL, run:
   wsl --update
   wsl --install --no-distribution
  

• The latest version of the Windows App Installer.

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

Windows (Manual)

• Windows Subsystem for Linux (WSL) 2 enabled: See Enable the Windows Subsystem for Linux, WSL basic commands, and Troubleshooting WSL 2.
  • After you enable WSL, run:
   wsl --update
   wsl --install --no-distribution
  
• Windows 10 or Windows 11.
• A container service like Podman or Docker Engine.

Linux

• A container service like Podman or Docker Engine.

Installation

Mac

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

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.

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

astro version

Windows with winget

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.

1. 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.36.0
   

2. Run astro version to confirm the Astro CLI is installed properly.

Windows (Manual)

Astronomer recommends using the Windows Package Manager winget command-line tool to install the Astro CLI.

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

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

4. Restart your machine.

Linux

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

Resolve installation issues

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

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

   brew update
   

2. Re-run the installation again:

   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:

   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.

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

   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:

brew install astronomer/tap/astro --without-podman

Already installed core formula

Uninstall it, then reinstall from the tap:

brew uninstall astro
brew install astronomer/tap/astro --without-podman

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