Install the Astro CLI

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:

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

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

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
   

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.

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.

Installation​

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

2. 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 Podman or Docker Desktop.

Installation​

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.

Prerequisites​

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

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

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.

1. Delete the existing astro.exe file on your machine.

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

3. Rename the file to astro.exe.

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

5. Restart your machine.

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

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

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:

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

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

sudo rm /usr/local/bin/astro