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
    • Astro CLI
    • Quickstart
    • CLI reference
      • astro completion
      • astro api
      • astro auth
      • astro config
      • astro context
      • astro dbt
      • astro deploy
      • astro deployment
      • astro dev
        • astro dev bash
        • astro dev build
        • astro dev init
        • astro dev kill
        • astro dev logs
        • astro dev object export
        • astro dev object import
        • astro dev parse
        • astro dev proxy
        • astro dev ps
        • astro dev pytest
        • astro dev restart
        • astro dev run
        • astro dev start
        • astro dev stop
        • astro dev upgrade-test
      • astro ide
      • astro login
      • astro logout
      • astro organization
      • astro otto
      • astro remote
      • astro run
      • astro team
      • astro telemetry
      • astro user create
      • astro version
      • astro workspace

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
CLI referenceastro dev

astro dev upgrade-test

Edit this page
Built with
The behavior and format of this command are the same for both Astro and Astro Private Cloud.

Test your local Astro project against a new version of Astro Runtime to prepare for an upgrade. Specifically, this command will run the following tests:

  • Identify major and minor version changes of the Python packages in your upgrade version.
  • Identify dag import errors that will appear after you upgrade.

See Test before upgrading your Astro project for more detailed information about usage and test results.

Usage

$astro dev upgrade-test

By default, the command runs all three available tests on your project against the latest version of Astro Runtime.

Options

OptionDescriptionPossible Values
-a, --airflow-versionThe equivalent of Airflow you want to upgrade to. The default is the latest available version. Note that the Astro CLI will still test against an Astro Runtime image based on the Airflow version you specify.Any valid Airflow version.
--build-secretsRun docker build --secret to mount a secret value to your Docker image.id=<your-secret-id>, src=<path-to-secret> . See Docker documentation.
-d, --dag-testOnly run dag tests. These tests check whether your dags will generate import errors after you upgrade.None
-i, --deployment-idSpecify a Deployment ID to test with an image from an Astro Deployment instead of the image listed in your Astro project Dockerfile.Any valid Deployment ID.
-n, --image-nameA custom image with an upgraded image tag to test against. The CLI creates a new Dockerfile in your project named upgrade-test-<old version>--<new version>/Dockerfile that includes your upgraded image, then tests against that Dockerfile.A valid image URL
-v, --runtime-versionThe version of Astro Runtime you want to upgrade to. The default is the latest available version.Any valid Astro runtime version.
--use-astronomer-certifiedTest against an Astronomer Certified distribution of Airflow. Must be used with --airflow-version.None
--version-testOnly run version tests. These tests show you how the versions of your dependencies will change after you upgrade.None
--fixAutomatically fix linting issues identified by the upgrade test using ruff.None
--lint-deprecationsInclude deprecation warnings in lint tests (set to false by default).true, false

Examples

  • Run all tests before upgrading to the latest version of Astro Runtime:

    $astro dev upgrade-test

  • Test an Astro project file against a the Astro Runtime distribution of a Airflow 2.6.3:

    $astro dev upgrade-test --airflow-version 2.6.3

  • Include deprecation warnings in lint tests (exports to ruff-lint-results.txt):

    $astro dev upgrade-test --lint-deprecations=true

  • Test only dependency version changes against the Astro Runtime distribution for Airflow 2.6.3:

    $astro dev upgrade-test --airflow-version 2.6.3 --provider-check

  • Test a custom image for an upgrade to a custom versioned distribution of Astro Runtime:

    $astro dev upgrade-test --image-name quay.io/example-organization/new-example-organization-image:1.0.7

    If you were upgrading from quay.io/example-organization/new-example-organization-image:1.0.5, for example, the Astro CLI creates a new Dockerfile located in upgrade-test-1.0.5--1.0.7/Dockerfile that contains the image you specified and tests against it.

Related Commands

  • astro dev pytest
  • astro dev parse