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.
Astro Runtime is a Docker image built and published by Astronomer that extends the Apache Airflow project to provide a differentiated data orchestration experience. This document provides a summary of changes made to each available version of Astro Runtime.
For release notes and provider package reference of Astro Runtime versions 10.x and older, see Astro Runtime docs archive.
Because Astronomer has separate maintenance life cycles for each major version of Astro Runtime, the same change can be introduced multiple times across major versions, resulting in multiple identical release notes. When a new major version releases, such as Astro Runtime 8.0.0, all changes from previously released versions are included in the new major version.
If you’re upgrading to receive a specific change, ensure the release note for the change appears either:
Within your target major version.
In any minor or patch version that was released before the first release (X.0.0) of your target major version. For example, a change in Astro Runtime 9.9.0, which released January 10 2024, is not guaranteed to appear in Runtime 10.0.0, which released December 8 2023, unless there is a release note for it in a subsequent Runtime 10 patch. However, a change in Astro Runtime 9.6.0, which released November 30 2023, is guaranteed to exist in Runtime 10.0.0 because 9.6.0 was released prior to 10.0.0.
If you use custom user roles, users with read-only access to Dags can no longer view the Dag list in the Airflow UI because the endpoint now requires additional permissions. Astronomer-provided roles aren’t affected. See Upgrade considerations: Runtime 3.2-3 and later for details.
Astro Runtime 3.2-2 includes support for Apache Airflow 3.2, which introduces Asset partitioning for granular pipeline orchestration, synchronous deadline alert callbacks, and continued progress toward full Task SDK separation. Airflow 3.2 includes the following changes:
Asset partitioning (AIP-76): Downstream Dags trigger only when the specific partition they depend on is updated, rather than firing on any partition change. This applies to date-partitioned S3 paths, Hive table partitions, BigQuery partitions, and other partitioned data stores. Includes CronPartitionTimetable, backfill support for partitioned Dags, and multi-asset partition scheduling.
Synchronous deadline alert callbacks: Building on the deadline alerts system introduced in Airflow 3.1, this release adds synchronous callback support. SyncCallback executes directly on the worker through the executor, with optional targeting of a specific executor through the executor parameter. You can also configure multiple deadline alerts per Dag.
Async PythonOperator support: PythonOperator now supports async callables. You can pass an async function as the python_callable and the operator correctly awaits it, enabling async I/O patterns without a custom operator.
UI enhancements:
Human-in-the-loop approval history with full audit trail
XCom management directly from the UI (add, edit, and delete)
Data redaction for sensitive fields in the UI and Public API
Segmented state bars for collapsed task groups and mapped tasks
One-click log copying, date range filters, and unified tooltips in Grid and Graph views
Performance: Rendered task instance fields cleanup is approximately 42 times faster for Dags with many mapped tasks. Retention is now based on the N most recent Dag runs instead of N most recent task executions.
Fixed an issue where Astro environment manager connections were not found in Airflow.
Upgraded to Airflow 3.2.0+astro.1, which includes:
Asset partitioning
Synchronous deadline alert callbacks
Async PythonOperator support
Upgraded the RHEL UBI base image from UBI 9 to UBI 10, and changed the OS variant image tag suffix from -ubi9 to -ubi. For more information, see Operating system variant images.
Astro Runtime 3.2-1 was restricted from use on April 16, 2026, after its initial release because of an issue where environment manager connections are not found. See Restricted Runtime versions.
Astro Runtime 3.1-8 was restricted from use on December 16, 2025, after its initial release because the Airflow version it is based on, Apache Airflow 3.1.4, was yanked from the OSS Airflow project.
This version of Runtime has a significant memory leak for Celery Workers. Astronomer recommends upgrading directly to Runtime 3.1-3 or switching to Astro Executor.
Additional improvements
Upgraded to Airflow 3.1.0+astro.2, which includes:
Fix scheduler crash with email notifications (#56429)
Emit log stream stopped warning as ndjson (#56474)
This version of Runtime has a significant memory leak for Celery Workers. Astronomer recommends upgrading directly to Runtime 3.1-3 or switching to Astro Executor.
Introducing Airflow 3.1
Astro Runtime 3.1-1 includes support for Apache Airflow 3.1, which includes a number of new features and improvements. Airflow 3.1 includes the following changes:
Human-in-the-loop: Bridge between fully automated processes and human expertise
This Runtime version introduces a new default behavior that could cause breaks depending on your configurations.
The Astro Runtime no longer installs Apache Airflow MySQL and PostgreSQL providers by default. If you need these providers, you must install them explicitly. See Add Airflow providers, Python packages, and operating system packages for how to add Airflow providers to your Astro project.
This version of Runtime has a significant memory leak for Celery Workers. Astronomer recommends upgrading directly to Runtime 3.1-3 or switching to Astro Executor.
Additional improvements
Upgraded to Airflow 3.0.6+astro.3, which includes:
This version of Runtime has a significant memory leak for Celery Workers. Astronomer recommends upgrading directly to Runtime 3.1-3 or switching to Astro Executor.
Additional improvements
Upgraded to Airflow 3.0.6+astro.2, which includes:
This version of Runtime has a significant memory leak for Celery Workers. Astronomer recommends upgrading directly to Runtime 3.1-3 or switching to Astro Executor.
This version of Runtime has a significant memory leak for Celery Workers. Astronomer recommends upgrading directly to Runtime 3.1-3 or switching to Astro Executor.
Restricted version
Airflow 3.0.5 was yanked due to a bug with conn.extra_dejson masking that causes tasks to fail (#54768).
This version of Runtime has a significant memory leak for Celery Workers. Astronomer recommends upgrading directly to Runtime 3.1-3 or switching to Astro Executor.
Additional improvements
Upgrade to Airflow 3.0.4+astro.2, which includes:
Fix scheduler crashes with DetachedInstanceError when processing executor events. #54334
Fix DetachedInstanceError when accessing DagRun.created_dag_version. #54362
Fix custom XCom backends not being used when BaseXCom.get_all() is called. #53814
Fix xcom_pull ignoring include_prior_dates parameter when map_indexes is not specified. #53809
Restore get_previous_dagrun functionality for task context. #53655
Fix log retrieval failures for in-progress tasks by properly configuring JWT authentication. #54444
Upgrade to Apache Airflow Task SDK 1.0.4+astro.2, which includes:
Fix custom XCom backends not being used when BaseXCom.get_all() is called. #53814
Fix xcom_pull ignoring include_prior_dates parameter when map_indexes is not specified. #53809
Restore get_previous_dagrun functionality for task context. #53655
This version of Runtime has a significant memory leak for Celery Workers. Astronomer recommends upgrading directly to Runtime 3.1-3 or switching to Astro Executor.
This version of Runtime has a significant memory leak for Celery Workers. Astronomer recommends upgrading directly to Runtime 3.1-3 or switching to Astro Executor.
Additional improvements
Upgraded to Airflow 3.0.3+astro.2, which includes:
Skips empty dag-run config rows and raises the SQL timeout for XCom migrations to avoid lock-timeout errors. #50788
Fixes sensor skipping in 3.x branching operators by correcting the SkipMixin import path. #53455
Triggers task-failure callbacks on the Dag processor when tasks are externally killed. #53143
Remote execution has a known incompatibility with Runtime 3.0-2. If you use remote execution, do not upgrade to or create Remote Deployments that use this version. A fix for the incompatibility will be released in v3.0-3.
If you created a new remote Deployment with 3.0-2, you cannot rollback to 3.0-1. You must either create a new remote Deployment with 3.0-1 or wait until the 3.0-3 patch and then upgrade.
If you upgraded a Deployment from 3.0-1 to 3.0-2, Astronomer advises you to downgrade your Deployments or rollback to 3.0-1 by using a Dockerfile change or by rolling back your Deployment in the Astro UI.
Astro Runtime 3.0-1 includes same-day support for Apache Airflow 3.0, which includes a number of new features and improvements. Airflow 3.0 includes the following changes:
Support for dag versioning
Enhanced and improved React-based Airflow UI
Support for remote dag execution
Scheduler-managed backfill
Event-driven and asset-driven scheduling
For more information about the major changes in this release, see the Airflow release notes.
Behavior changes
New naming convention for Runtime release versions. Previously, versions were noted as XX.X.X, now versions are named as XX.X-X.
Astro Runtime for 3.0 and higher includes only the provider packages required to run on Astro. Previous versions contained additional providers, and if you are using those providers you must explicitly add them to your requirements.txt.
Runtime docs for versions that are past their End of Basic Support date, below v6.0.0, have been moved to the Astronom Docs Resources archive.
The Docker registry URL for Runtime images has changed for Airflow 3.x. For details, see Docker Registry URL changes.
Pip package resolution
With Runtime 3.0, Python package resolution has switched by default from pip to uv, which is intended as a fast drop in replacement for pip. However, uv has a different behavior for packages that exist on multiple indexes, because pip’s behavior is unsafe against dependency confusion attacks. If you rely on the pip behavior, you can add # ASTRO_RUNTIME_USE_PIP to your requirements.txt file to use pip instead of uv. You can also opt to install your dependencies in a separate RUN line on your Dockerfile instead of using Runtime’s built-in pip installation.
Docker Compose override changes
When using astro dev start, you can specify a docker-compose.override.yml. If you specified any overrides for the webserver container, these break your ability to use astro dev start because there is no longer a webserver container. Replace all references to webserver with api-server.
Docker Registry URL changes
Starting with Airflow 3.x, Runtime Docker images are hosted at a new registry:
astrocrpublic.azurecr.io/runtime:<version>
Airflow 2.x images are still available under the original registry:
quay.io/astronomer/astro-runtime:<version>
but can also be pulled from the new domain as an alternative:
Skip dataset-triggered dags without SerializedDagModel #63546
Prevent scheduler crash on AF3.2+ downgrade (interval timetables)
Fix log groups collapsing on auto-refresh in Logs view #65378
Guard Grid task-group selections in legacy details flow
Add INFO-level logging to dataset scheduling path #63958
Remove sunset Astronomer Registry link from Airflow UI #3144
Security fixes
Fix 22 endorctl-flagged CVEs by bumping aiohttp, urllib3, requests, microsoft-kiota-http, Mako, Authlib, Pygments, lxml, pytest, and pyarrow
Breaking changes
Bumped snowflake-connector-python 3.15.0 → 4.5.0 and lxml 5.3.2 → 6.1.0 to fix CVEs. Snowflake 4.x and lxml 6.x each drop deprecated APIs — review DAGs that use them directly.
Astro Runtime 13.5.0 has been restricted from use due to a known issue where the Airflow webserver returns 500 errors for existing user sessions when upgrading from previous versions. This is caused by an incompatibility between session cookies from earlier versions and the updated flask-session dependency included in FAB 1.5.4. See Restricted Runtime versions.
Update astronomer-providers-logging to 1.6.2. This adds support for writing task logs to a secondary S3 bucket.
Fix get_health endpoint to return None for inactive standalone Dag processors, preventing them from being reported as unhealthy.
Upgraded the major, minor, and patch versions of several open-source provider packages. See Astro Runtime 13.0.0 provider packages. As this release includes major provider updates, this release introduces breaking changes in dags. These issues can be resolved by updating provider-specific changes in the dags.
RHEL UBI 9 images are now officially supported starting with version 12.5. In addition, the following changes have been made since the initial release:
Astro Runtime 12.0.0 includes same-day support for Apache Airflow 2.10, which includes a number of new features and improvements. Airflow 2.10 includes the following changes:
Adds decorators for task flow (@skip_if, @run_if) to make it easier to apply whether or not to skip a task.
You can now see TaskInstanceTry History in the Airflow UI
Enable ending the task directly from the triggerer without going into the worker.
Extended dataset dependencies to support dynamic Dataset Event Emission and Dataset Creation.
A new object, DatasetAlias, is available to support dynamic Dataset Event Emission and Dataset Creation (#40478)
Implement accessors to read dataset events defined as inlet (#39367)
Since Airflow 2.10 uses Python 3.12, some Python modules have reached end of life, like imp, that might create errors in your dags if you still use them. See Upgrade considerations: Runtime 12 for more information.
Fixed a bug in the check served logs logic that caused the UI to show an erroneous 404 error if the user was looking at the logs for a non-running try #41272
Fixed a bug where clicking on a run_id in a task_instance or dag_run list incorrectly opened a different run_id#42138
Fixed a bug where FAB config options, such as [fab] update_fab_perms, were not checking for values in the deprecated webserver config section. For example, [webserver] update_fab_perms (#40317)
Astro Runtime 11.5.0 includes same-day support for Apache Airflow 2.9.2. Airflow 2.9.2 contains a number of bug fixes including:
Resolved a bug where valid dags that worked in Airflow 2.8 and had outlet datasets with specific URIs stopped working depending on how the URI was formatted (#39670)
Resolved an issue where the object storage XCOM backend did not serialize correctly, causing custom XCOM backends to sometimes fail (#39313)
Fixed a bug affecting custom actions in Airflow plugins that prevents users from running an Astro Runtime environment locally for Astro Runtime versions 11.0.0-11.2.0. Deployments running these versions on Astro are not affected. To continue using 11.0.0-11.2.0 locally, set AIRFLOW__ASTRONOMER__UPDATE_CHECK_INTERVAL=0 in your Astro project .env file (#39421)
Additional improvements
Upgraded some OSS providers’ minor and patch versions
Due to an issue related to using custom FAB actions in Airflow plugins, you might experience an error when you run this version of Astro Runtime locally using the Astro CLI. To resolve this issue, either upgrade directly to Astro Runtime 11.3.0 or set AIRFLOW__ASTRONOMER__UPDATE_CHECK_INTERVAL=0 in your Astro project .env file.
Early access Airflow bug fixes
Fixed a bug where airflow db migrate would throw an error (#39246)
Due to an issue related to using custom FAB actions in Airflow plugins, you might experience an error when you run this version of Astro Runtime locally using the Astro CLI. To resolve this issue, either upgrade directly to Astro Runtime 11.3.0 or set AIRFLOW__ASTRONOMER__UPDATE_CHECK_INTERVAL=0 in your Astro project .env file.
Added functionality for using plugins to generate custom menu items in the Airflow UI. This feature will be fully available on Astro in a future release.
Due to an issue related to using custom FAB actions in Airflow plugins, you might experience an error when you run this version of Astro Runtime locally using the Astro CLI. To resolve this issue, either upgrade directly to Astro Runtime 11.3.0 or set AIRFLOW__ASTRONOMER__UPDATE_CHECK_INTERVAL=0 in your Astro project .env file.
Airflow 2.9.0
Astro Runtime 11.0.0 includes same-day support for Apache Airflow 2.9, which includes a number of new features and improvements. Airflow 2.9 includes the following changes:
New data-aware scheduling lets you use conditional logic (AND / OR) to schedule dags.
You can now create your own labels for dynamically mapped tasks with templates, which makes it easier to search through mapped task instances.
External XCom backends can now be configured to use object storage.
Delivered several significant improvements to the Airflow UI. For example, you can now filter, view, and create datasets through the Airflow UI.
New Listener API methods are considered stable and suitable for use in production.
Added the ability to automatically pause a dag after a pre-defined number of sequentially failed runs.
Dataset URIs are validated when you enter them, and must conform to the rules set in AIP-60. See the Dataset documentation for more information.
Airflow now supports Python 3.12. However, Pendulum 2 does not support Python 3.12. If you upgrade to Python 3.12 and want to use Airflow, you also need to upgrade to Pendulum 3.
Refer to the Airflow release notes for more information about any limitations in Python 3.12 support.
Bug fixes
Fixed a bug where after a task failed, and no longer exists in a dag, you can now still access details about the dag in the Grid View of the Airflow UI.
Fixed a bug where Airflow would show failed_upstream when a dynamically mapped task was skipped.
In the Python task decorator, you can only have None as the default parameter for context parameters.
