Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Concepts and Architecture

What Changed in Airflow 3: Task SDK, API Server and More

Learn the main differences between Airflow 2 and Airflow 3: the Task SDK, API server, DAG versioning, assets, new imports and removed features, with migration tips.

Airflow 3, released in 2025, is the biggest change since Airflow 2. Most DAGs need only small edits, but the architecture underneath is different, and many tutorials online still show Airflow 2 code. This lesson lists what changed, what that means for the code you write, and how to read older examples.

Everything here is read-only reference. The stand-ins translate old import paths and check a DAG for Airflow 2 patterns, which are the kind of work a migration really involves. Check the official release notes for the exact version you install, because details evolve between 3.x releases.

The big picture

flowchart LR
    subgraph A2["Airflow 2"]
        W2["Worker"] -->|"direct SQL"| D2[("Database")]
    end
    subgraph A3["Airflow 3"]
        W3["Worker + Task SDK"] -->|"HTTP"| API["API server"]
        API --> D3[("Database")]
    end

In Airflow 3 tasks no longer talk to the database; they use the API server.

Task Execution Interface and Task SDK

Workers now communicate through an HTTP API using a stable client, the Task SDK (airflow.sdk). Benefits:

  • Security: task code does not need database credentials or direct access.
  • Remote execution: workers can run in other networks or languages, because the interface is a defined protocol.
  • Stable authoring API: the public names for writing DAGs (DAG, task, dag, Asset, Variable, Connection...) live in airflow.sdk.
Python
# Airflow 3
from airflow.sdk import DAG, dag, task, Asset, Variable

In Airflow 2 the same classes came from various places (airflow.models, airflow.decorators, airflow.datasets).

New and separate processes

  • The API server replaces the old webserver and also serves workers.
  • The DAG processor is its own process instead of living inside the scheduler.
  • The UI was rebuilt with React and gained dark mode, new grid and graph views.

DAG versioning

When a DAG's structure changes, Airflow 3 keeps versions of it. A run is tied to the version it started with, so the UI can show the code and graph as it was for an old run, even after you edited the file. In Airflow 2 the UI always showed the latest structure.

Event-driven scheduling and assets

Airflow 2 had "datasets"; Airflow 3 renames and extends them to assets. A DAG can run when an asset is updated by another DAG or by an external event (a message arriving through a watcher). You write schedule=[Asset("s3://bucket/sales.parquet")]. See the scheduling chapter.

Scheduling defaults changed

  • catchup now defaults to False.
  • A cron string such as "0 6 * * *" now creates a run at that exact time using the cron-trigger timetable. In Airflow 2 a cron string created data intervals, so the run for "6:00 today" actually started at "6:00 tomorrow". If you want the old interval behaviour you choose the interval timetable explicitly (or set the matching config option).
  • logical_date can be empty for manual and asset-triggered runs; use run_after or the data interval fields where you need a date.
  • The old execution_date name is gone; use logical_date.
  • schedule_interval and timetable arguments are gone; use schedule.

Removed or moved features

Airflow 2 Airflow 3
from airflow import DAG from airflow.sdk import DAG
from airflow.decorators import task, dag from airflow.sdk import task, dag
from airflow.operators.bash import BashOperator from airflow.providers.standard.operators.bash import BashOperator
from airflow.operators.python import PythonOperator from airflow.providers.standard.operators.python import PythonOperator
from airflow.datasets import Dataset from airflow.sdk import Asset
schedule_interval="@daily" schedule="@daily"
execution_date logical_date
SubDAGs removed: use task groups
Direct database access from tasks use the Task SDK / REST API
airflow db init airflow db migrate

Many old imports keep working for a while and print deprecation warnings, so you can migrate step by step.

Migration tips

  1. Upgrade to the latest Airflow 2.x first and fix all deprecation warnings.
  2. Run the official linter, ruff check --select AIR30, which flags code that must change (the AIR rules were built for this).
  3. Move imports to airflow.sdk and the standard provider.
  4. Review every cron schedule and decide whether you want interval or trigger semantics.
  5. Remove any code that reads the metadata database directly from tasks.
  6. Test on a copy of your database with airflow db migrate.

Stand-in: rewrite old imports

This stand-in uses a table of replacements to modernise import lines, the way a small migration script would.

Python Stand-in: Airflow 2 to 3 import rewriter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: a linter for Airflow 2 habits

A second helper scans DAG source text for patterns that no longer work in Airflow 3.

Python Stand-in: find Airflow 2 patterns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Should you learn Airflow 2 or 3?

Learn Airflow 3: it is the current line and new installs use it. When you meet Airflow 2 code in books, blog posts or an existing company codebase, the concepts are identical (DAGs, tasks, operators, scheduling, XCom). Only the import paths, some defaults and the deployment architecture differ. This course writes Airflow 3 code and notes the Airflow 2 form when it differs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main purpose of the Task SDK in Airflow 3?

    The Task SDK defines the public authoring names and the interface workers use via the API server.
  2. 2. Which line is the Airflow 3 way to set the schedule?

    schedule is the single argument in Airflow 3; schedule_interval was removed.
  3. 3. What replaced SubDAGs?

    SubDAGs were removed; task groups give the same visual grouping without separate DAG runs.
  4. 4. What does DAG versioning give you?

    Each run is tied to the version of the DAG it started with.

Summary

  • Airflow 3 introduces the Task SDK, a separate API server and DAG processor, DAG versioning and assets.
  • Imports moved to airflow.sdk and airflow.providers.standard; schedule replaces schedule_interval; logical_date replaces execution_date.
  • Defaults changed: catchup=False, cron strings use the trigger timetable.
  • Migrate in steps: latest Airflow 2.x, fix warnings, run the linter, then upgrade.

Next: Ways to define a DAG