Airflow 2 to Airflow 3: what breaks and how to move

Airflow 2 reached end of life on 22 April 2026, so it gets no more fixes, security fixes included. Most of the move to Airflow 3 happens while you are still on Airflow 2: you fix your Dags with ruff's AIR rules, switch to the new imports, then migrate the database in one step. The part that hurts teams is not the error messages. It is the 3 or 4 scheduling changes that throw no error at all.

Airflow 2Airflow 3

1. 22 Apr 2025Airflow 3.0 ships. Tasks now reach the database only through the new API server.
2. 25 Sep 2025Airflow 3.1. The old import paths start printing deprecation warnings.
3. 22 Oct 2025Airflow 2 moves to limited maintenance.
4. 7 Apr 2026Airflow 3.2.
5. 22 Apr 2026Airflow 2 reaches end of life. 2.11 is its last line.
6. 6 Jul 2026Airflow 3.3.
7. 6 Nov 2026Airflow 3.4: task loops, Dags in other languages, psycopg3 by default, Python 3.11 or newer.

Release and support dates as Airflow publishes them on its announcements and supported versions pages. Source: Apache Airflow, Supported versions.

What changed in Airflow 3, underneath

In Airflow 3 your task code can no longer touch Airflow's own database. That one decision explains most of the upgrade.

In Airflow 2 every part of the system, the scheduler, the webserver and the workers running your tasks, held a connection to the metadata database. Task code ran in the same process as Airflow's internals, so a task could import a session and read or change any table. It was convenient and it was a mess: a bad task could block the database, and every worker needed database credentials.

Airflow 3 puts an API server in front of the database. It serves the UI, the REST API and a new Task Execution API, and workers talk to that instead. Tasks get what they need through the Task SDK, a stable set of imports under airflow.sdk. The Dag processor and the triggerer still run your Dag files with database access, but the code inside a task does not.

3 things follow from it:

• A task that queried Airflow's tables, to count failed runs or clean up old XComs, stops working. Use the Airflow Python client against the REST API with a token. Pointing a Postgres hook at the metadata database still works today, but Airflow warns that the schema is not a public API and that this route breaks from 3.2 onwards.
• The webserver is gone. You start airflow api-server instead, and the Dag processor runs as its own process, airflow dag-processor, even on a laptop.
• Imports move. from airflow.decorators import dag, task becomes from airflow.sdk import dag, task, Dataset becomes Asset, and the old paths print deprecation warnings from 3.1 on.

What breaks when you upgrade from Airflow 2

Pick what your own Dags and deployment use. Each item shows what breaks and when in the upgrade you fix it.

Try itWhat will break when you move to Airflow 3?

Your Airflow 2 setup uses

·None of these·BashOperator or PythonOperator imports·execution_date, prev_ds or next_ds·SubDAGs·SLAs·Cron schedules that read the data interval·Tasks that query Airflow's own database·Python 3.10 or older·CeleryKubernetes, LocalKubernetes or Sequential executor·Flask-AppBuilder plugins or webserver_config.py·A Postgres database through psycopg2·Dags that rely on catchup by default·xcom_pull() without task_ids·Scripts that call /api/v1

5 to fix

On Airflow 2, before you switch

• BashOperator or PythonOperator imports

  The core operators, sensors and triggers moved to a provider package.

  Install apache-airflow-providers-standard on Airflow 2 and switch the imports there.

• execution_date, prev_ds or next_ds

  These context variables are gone. A Dag that still reads one fails.

  Use logical_date or the data interval. ruff check dags/ --select AIR301 finds each one.

• Cron schedules that read the data interval

  A bare cron string now means CronTriggerTimetable, with no data interval.

  Set create_cron_data_intervals = True before the upgrade. Changing it later skips one run.

During the upgrade

Nothing from your list.

Right after, before you trust the runs

• Dags that rely on catchup by default

  catchup_by_default is now False, so missed runs are not filled in.

  Set catchup=True on the Dags that need it.

• xcom_pull() without task_ids

  It now reads only the current task's XComs and returns nothing from others.

  Pass task_ids every time you read another task's value.

Most of the list is fixed on Airflow 2, before anything is installed. The removals are the obvious ones: SubDAGs become TaskGroups or separate Dags linked by assets, SLAs become Deadline Alerts, and the CeleryKubernetes, LocalKubernetes and Sequential executors give way to several executors configured at once. The /api/v1 REST API is now /api/v2, and sign-in routes start with /auth, so an OAuth redirect such as /oauth-authorized/google becomes /auth/oauth-authorized/google.

How to upgrade from Airflow 2 to Airflow 3, step by step

Do it in this order. Each step is small, and only one of them touches production.

1. Get to the latest Airflow 2. The upgrade guide needs 2.7 or later and recommends the newest 2.x release.
2. Check your Python. Airflow 3.4 needs Python 3.11 or newer.
3. Clean up. Back up the metadata database (shut Airflow down first if your database cannot take a hot backup), run airflow db clean to trim old rows so the schema migration runs faster, and make sure airflow dags reserialize finishes with no errors.
4. Fix the Dags on Airflow 2 with ruff, below, and install apache-airflow-providers-standard, which now holds BashOperator, PythonOperator, ExternalTaskSensor and FileSensor. It installs on Airflow 2, so the new imports can ship before the upgrade.
5. Take direct database access out of tasks.
6. Upgrade. Install Airflow 3, then:

airflow config update          # report settings that changed
airflow config update --fix    # rewrite them for Airflow 3
airflow db migrate             # the schema migration, the longest step

7. Start the new processes. airflow api-server replaces airflow webserver, and airflow dag-processor runs beside the scheduler. On the Helm chart, the webserver settings move to apiServer.
8. Check sign-in. Simple Auth is now the default auth manager. To keep Flask-AppBuilder logins (OAuth, LDAP), install the FAB provider and set auth_manager to its FabAuthManager, and update any custom webserver_config.py to the new security manager class.

Run the old and new deployments side by side on a copy of the database if you can. The next 2 sections are why.

How to find the breaking changes in your Dags

Ruff, the Python linter, has rules written by the Airflow project for this upgrade. Use ruff 0.13.1 or later. AIR301 and AIR302 flag what breaks; AIR311 and AIR312 flag what still works but should change.

ruff check dags/ --select AIR301                 # list what breaks
ruff check dags/ --select AIR301 --show-fixes    # show the fixes
ruff check dags/ --select AIR301 --fix           # apply the safe ones
ruff check dags/ --select AIR301 --fix --unsafe-fixes   # also rewrite import paths

The unsafe fixes change import paths and can change behaviour, so read the diff. Add the F401 rule afterwards to remove the imports left unused. Run this in CI on Airflow 2 and the Dags are ready before the platform team touches anything.

The changes that fail without an error

These are the ones to test with real runs, because nothing goes red.

Cron schedules. In Airflow 3 a bare cron string such as "0 6 * * *" means CronTriggerTimetable: the run happens at 06:00 and has no data interval to process. In Airflow 2 the same string meant "process the interval that just ended". A Dag that reads data_interval_start to pick yesterday's partition now gets something different. To keep the old meaning, set create_cron_data_intervals = True before you upgrade. Change it after Airflow 3 runs exist and one scheduled run is skipped. Our cron expression builder writes the cron Airflow reads and shows the next runs in your time zone, which helps when you compare old and new.

Catchup. catchup_by_default is now False. A Dag that relied on Airflow filling in missed intervals after a pause just carries on from today. Set catchup=True on the Dags that need it.

XCom reads. xcom_pull() with no task_ids used to search wider. In Airflow 3 it reads only the current task's values, so a downstream task gets None where it used to get data. Pass task_ids every time.

Manual runs. When someone triggers a run by hand with a date, don't assume the data interval matches it. Read logical_date when you need the date the person asked for.

Each of these is a pipeline that reruns cleanlyIdempotent Pipelines and Exactly-OnceA pipeline step is idempotent when running it twice gives the same result as running it once. That is what makes retries safe, and it is how systems that deliver a message more than once still count it exactly once. on Airflow 2 and quietly processes the wrong slice on Airflow 3. Compare row counts or partition dates between the old and new runs for a few days before you switch off Airflow 2.

Should you go straight to Airflow 3.4?

Yes, if you are starting now. There is no reason to land on 3.0 and upgrade again. Airflow 3.4.0 came out on 6 November 2026 and adds a few changes of its own to plan for:

• Python 3.11 or newer. 3.10 support is removed.
• psycopg3 for Postgres. A plain postgresql:// connection string is rewritten to postgresql+psycopg://. If something of yours needs psycopg2, install the matching provider extra.
• One run per asset event. A Dag scheduled on a single asset, or on assets joined with OR, now gets one run for each event instead of one run for a batch of them. Set batch_asset_events=True to keep batching.
• More database connections. The API server opens a second async pool, so it can hold up to twice the connections your pool settings suggest. Check your database's connection limit.
• Worker heartbeats. [workers] max_failed_heartbeats is now the only retry control for heartbeats, and its default went from 3 to 30.

What task loops in Airflow 3.4 do

Task loops repeat a task group until a condition says stop, which Airflow could not express before without a sensor or a self-triggering Dag. A loop always runs once, stops when its until check returns true, and never runs more than max_iterations times. The shape of Airflow's own example:

from airflow.sdk import dag, task, task_group

@task
def improve(*, loop):
    # loop.previous holds what the last pass returned
    ...

@task
def evaluate(estimate):
    ...
    return {"estimate": estimate, "error": error}

@task_group
def refine():
    return evaluate(improve())

def accurate_enough(*, loop):
    return loop.result["error"] < 0.01

@dag
def refine_estimate():
    refine.loop(max_iterations=10, until=accurate_enough)

refine_estimate()

until is a plain Python function, not a task. It gets the last pass's result and returns true or false. Loops cannot be nested or mapped as a whole, though the tasks inside one pass can be mapped. If you run a custom XCom backend that overrides serialize_value, it must also implement store_value, because each pass of a loop writes its own task instances.

3.4 also lets you write Dags in TypeScript, Go, Java or a YAML format. Airflow marks that framework and its language SDKs experimental, so keep production Dags in Python for now.

Where to start

Run ruff check dags/ --select AIR301 on your repository today, on Airflow 2. The number it prints is a fair measure of the work. Then list every Dag with a cron schedule that reads its data interval, and decide on create_cron_data_intervals before the upgrade, not after. If you are choosing an orchestrator rather than upgrading one, Airflow vs Dagster vs Prefect runs the same pipeline on all 3.