For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
      • AstroFully-managed data operations, powered by Apache Airflow.
      • Astro Private CloudRun Airflow-as-a-service in your environment.
      • Professional ServicesExpert Airflow services for your enterprise's success.
    • Tools
      • Cosmos
      • Orbiter
      • CLI
      • AI SDK
      • Agents
      • Blueprint
      • UpdatesThe State of Airflow 2026See the insights from over 5,800 data practitioners in the full report. Download Now ➔
  • Customers
  • Docs
    • Insights
      • Blog
      • Webinars
      • Resource Library
      • Events
    • Education
      • Academy
      • What is Airflow?
  • Pricing
Get Started Free
    • Overview
      • Upgrade Astronomer
      • Apply a config change
        • Overview
        • Create a Deployment
        • Scale Airflow components and resources
        • Clean up and delete Deployments
        • Clean up and delete task metadata
        • Environment variables
        • Customize resource usage
          • Overview
          • Deploy a project image
          • Deploy DAGs using the CLI
          • Deploy a prebuilt image
          • Roll back a deploy
          • Configure git-sync deploys
          • Configure NFS deploys
    • Book Office Hours

Product

  • Platform Overview
  • Astro
  • Astro Observe
  • Astro Private Cloud
  • Security & Trust
  • Pricing

Tools & Services

  • Cosmos
  • Docs
  • Professional Services
  • Product Updates

Use Cases

  • AI Ops
  • Data Observability
  • ETL/ELT
  • ML Ops
  • Operational Analytics
  • All Use Cases

Industries

  • Financial Services
  • Gaming
  • Retail
  • Manufacturing
  • Healthcare
  • All Industries

Resources

  • Academy
  • eBooks & Guides
  • Blog
  • Webinars
  • Events
  • The Data Flowcast Podcast
  • All Resources

Airflow

  • What is Airflow
  • Airflow on Astro
  • Airflow 3.0
  • Airflow Upgrades
  • Airflow Use Cases
  • Airflow 2.x End of Life

Company

  • Our Story
  • Customers
  • Newsroom
  • Careers
  • Contact

Support

  • Knowledge Base
  • Status
  • Contact Support
GitHubYouTubeLinkedInx
  • Legal
  • Privacy
  • Terms of Service
  • Consent Preferences

  • Do Not Sell or Share My Personal information
  • Limit the Use Of My Sensitive Personal Information

Apache Airflow®, Airflow, and the Airflow logo are trademarks of the Apache Software Foundation. Copyright © Astronomer 2026. All rights reserved.

LogoLogo
On this page
  • Prerequisites
  • Step 1: (Optional) Create a Docker image
  • Step 2: Deploy code
  • Additional deploy options
AdministrationManage DeploymentsDeploy options

Deploy a prebuilt image

Edit this page
Built with

By default, running astro deploy with the Astro CLI builds your project into a Docker image and deploys it to Astronomer Software. In some cases, you might want to skip the build step and deploy a prebuilt Docker image instead.

Deploying a prebuilt Docker image allows you to:

  • Test a single Docker image across Deployments instead of rebuilding it each time.
  • Reduce the time it takes to deploy. If your project has a number of packages that take a long time to install, it can be more efficient to build it separately.
  • Specify additional mounts and arguments in your project, which is required for setups such as installing Python packages from private sources.

Prerequisites

In order to push code to a Deployment on Astronomer, you must have:

  • The Astro CLI installed.
  • Access to an Astronomer platform at https://app.BASEDOMAIN.
  • An Astronomer Workspace with at least one active Airflow Deployment.
  • If your image names include a sha, you also need to configure the CLI to set sha_as_tag as true.

Step 1: (Optional) Create a Docker image

  1. Run docker build from an Astro project directory or specify the command in a CI/CD pipeline. This Docker image must be based on Astro Runtime and be available in a local Docker registry. If you run this command on an Apple M1 computer or on a computer with an ARM64 processor, you must specify --platform=linux/amd64 or else the deploy will fail. Astro Deployments require an AMD64-based image and do not support ARM64 architecture.

  2. (Optional) Test your Docker image in a local Airflow environment by adding the --image-name=<image-name> flag to any of the following commands:

    • astro dev start
    • astro dev restart
    • astro dev parse
    • astro dev pytest

Step 2: Deploy code

If you have the image locally, run the following command or specify it in a CI/CD pipeline:

1astro deploy --image-name=<image-name>

Additional deploy options

If your image is in a remote repo, add the --remote flag with the path for the image and the --runtime-version.

1astro deploy --image-name=<image-name> --remote=<path> --runtime-version=<runtime-version>
2
3If you have DAG-only deploys enabled, you can also use the `--image` flag to deploy a prebuilt image without also deploying your DAGs folder. Use:
4
5```sh
6astro deploy --image-name=<image-name> --image

For more information about the different command options, such as specifying a remote private repository or configuring an Astronomer Runtime version, see the CLI command reference.

If you build an AMD64-based image and run astro deploy from an Apple M1 computer, you might see a warning in your terminal. You can ignore the warning.

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform
(linux/arm64/v8) and no specific platform was requested