{"id":1906,"library":"apache-airflow-task-sdk","title":"Apache Airflow Task SDK","description":"The Apache Airflow Task SDK provides Python-native interfaces for defining Directed Acyclic Graphs (DAGs), executing tasks in isolated subprocesses, and interacting with Airflow resources at runtime. Its primary goal is to decouple DAG authoring from Airflow internals, offering a forward-compatible and stable interface across Airflow versions. The library is currently at version 1.2.0 and receives frequent updates, aligning with the release cadence of Apache Airflow 3.x.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/apache/airflow/tree/main/airflow/task-sdk","tags":["apache-airflow","airflow","dag","task","orchestration","workflow","etl"],"install":[{"cmd":"pip install apache-airflow-task-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python version for compatibility.","package":"python","optional":false},{"reason":"The Task SDK is designed to work with Apache Airflow, specifically Airflow 3.x, though it aims for decoupling, core Airflow components are still necessary for execution.","package":"apache-airflow","optional":false}],"imports":[{"symbol":"dag","correct":"from airflow.sdk import dag"},{"symbol":"task","correct":"from airflow.sdk import task"},{"note":"Airflow 3.x and the Task SDK consolidate core authoring interfaces under `airflow.sdk`. Legacy imports will be removed.","wrong":"from airflow.models.dag import DAG","symbol":"DAG","correct":"from airflow.sdk import DAG"},{"note":"Use the stable `airflow.sdk` path for operators in Airflow 3.x.","wrong":"from airflow.models.baseoperator import BaseOperator","symbol":"BaseOperator","correct":"from airflow.sdk import BaseOperator"},{"symbol":"Connection","correct":"from airflow.sdk import Connection"},{"symbol":"Variable","correct":"from airflow.sdk import Variable"},{"symbol":"Param","correct":"from airflow.sdk import Param"},{"note":"XComArg is used for data passing between TaskFlow API tasks. TaskGroups replace SubDAGs in Airflow 3.x.","wrong":"from airflow.utils.task_group import TaskGroup","symbol":"XComArg","correct":"from airflow.sdk import XComArg"},{"note":"The `get_current_context()` function is the recommended way to retrieve the execution context dictionary, offering a cleaner signature than `**context`.","wrong":"def my_task(**context): ti = context['ti']","symbol":"get_current_context","correct":"from airflow.sdk import get_current_context"}],"quickstart":{"code":"import pendulum\nfrom airflow.sdk import dag, task\n\n@task\ndef my_task():\n    print(\"Hello from a Task SDK task!\")\n\n@dag(\n    schedule=None,\n    start_date=pendulum.datetime(2023, 1, 1, tz=\"UTC\"),\n    catchup=False,\n    tags=[\"example\"],\n)\ndef example_simplest_dag():\n    my_task()\n\nexample_dag_instance = example_simplest_dag()","lang":"python","description":"This quickstart defines a simple Airflow DAG using the Task SDK's `@dag` and `@task` decorators. The `my_task` function is decorated as an Airflow task, and `example_simplest_dag` is a decorated function that defines the DAG structure and invokes the task. This pattern decouples DAG authoring from Airflow internals."},"warnings":[{"fix":"Refactor task code to use the Task SDK's interfaces for interacting with Airflow resources (e.g., Connections, Variables, XComs) instead of direct database access.","message":"Direct metadata database access from task code is now restricted in Airflow 3.x. Tasks can no longer directly import and use Airflow database sessions or models. All runtime interactions must go through a dedicated Task Execution API via the Task SDK.","severity":"breaking","affected_versions":"Airflow 3.0.0+"},{"fix":"Update all DAG and task-related imports to use the `airflow.sdk` namespace. For example, `from airflow.models.dag import DAG` becomes `from airflow.sdk import DAG`.","message":"All DAGs must update their imports to refer to `airflow.sdk` instead of using internal Airflow modules directly. Deprecated legacy import paths (e.g., `airflow.models.dag.DAG`, `airflow.decorator.task`) will be removed in future Airflow versions.","severity":"breaking","affected_versions":"Airflow 3.0.0+"},{"fix":"Migrate SubDAG implementations to use TaskGroups for grouping tasks, and explore Assets and Data Aware Scheduling for managing complex data dependencies.","message":"SubDAGs are replaced by TaskGroups, Assets, and Data Aware Scheduling in Airflow 3.x. Existing SubDAGs will need to be refactored.","severity":"breaking","affected_versions":"Airflow 3.0.0+"},{"fix":"Transition from using SLAs to implementing Deadline Alerts for monitoring task and DAG adherence to time constraints.","message":"SLAs (Service Level Agreements) are deprecated and replaced with Deadline Alerts in Airflow 3.x.","severity":"deprecated","affected_versions":"Airflow 3.0.0+"},{"fix":"Explicitly set `catchup=True` in your DAG definition if you intend for it to run for past missed schedules. Otherwise, review your DAGs to ensure `catchup=False` is the desired behavior.","message":"The `catchup_by_default` DAG parameter is now `False` by default in Airflow 3.x. This can lead to unexpected behavior if DAGs were implicitly relying on catchup being enabled.","severity":"gotcha","affected_versions":"Airflow 3.0.0+"},{"fix":"Update task definitions to import `get_current_context` from `airflow.sdk` and call it within the task function to retrieve the execution context.","message":"When passing context to tasks, the traditional `def my_task(**context)` signature is being superseded. While still functional, the recommended approach in the Task SDK is to explicitly retrieve context using `airflow.sdk.get_current_context()`.","severity":"gotcha","affected_versions":"Airflow 3.0.0+"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}