Registry / workflow / apache-airflow-task-sdk

apache-airflow-task-sdk

library1.3.1pypypi✓ verified 24d ago

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.

workflow

pip install apache-airflow-task-sdk

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · APACHE-AIRFLOW-TAS

apache-airflow-task-sdk

workflowpythonv1.3.1

Install

23.7s avg

Import

4821ms

Disk

256MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 4.990s · 256.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 23.7s · import 4.652s · 255MB

256MB installed

● package 256MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

dag

✓ from airflow.sdk import dag

task

✓ from airflow.sdk import task

DAG

✓ from airflow.sdk import DAG

✗ from airflow.models.dag import DAG

Airflow 3.x and the Task SDK consolidate core authoring interfaces under `airflow.sdk`. Legacy imports will be removed.

BaseOperator

✓ from airflow.sdk import BaseOperator

✗ from airflow.models.baseoperator import BaseOperator

Use the stable `airflow.sdk` path for operators in Airflow 3.x.

Connection

✓ from airflow.sdk import Connection

Variable

✓ from airflow.sdk import Variable

Param

✓ from airflow.sdk import Param

XComArg

✓ from airflow.sdk import XComArg

✗ from airflow.utils.task_group import TaskGroup

XComArg is used for data passing between TaskFlow API tasks. TaskGroups replace SubDAGs in Airflow 3.x.

get_current_context

✓ from airflow.sdk import get_current_context

✗ def my_task(**context): ti = context['ti']

The `get_current_context()` function is the recommended way to retrieve the execution context dictionary, offering a cleaner signature than `**context`.

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.

import pendulum from airflow.sdk import dag, task @task def my_task(): print("Hello from a Task SDK task!") @dag( schedule=None, start_date=pendulum.datetime(2023, 1, 1, tz="UTC"), catchup=False, tags=["example"], ) def example_simplest_dag(): my_task() example_dag_instance = example_simplest_dag()

Debug

Known issues

breakingDirect 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.

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.

affects: Airflow 3.0.0+

breakingAll 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.

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`.

affects: Airflow 3.0.0+

breakingSubDAGs are replaced by TaskGroups, Assets, and Data Aware Scheduling in Airflow 3.x. Existing SubDAGs will need to be refactored.

fix

Migrate SubDAG implementations to use TaskGroups for grouping tasks, and explore Assets and Data Aware Scheduling for managing complex data dependencies.

affects: Airflow 3.0.0+

deprecatedSLAs (Service Level Agreements) are deprecated and replaced with Deadline Alerts in Airflow 3.x.

fix

Transition from using SLAs to implementing Deadline Alerts for monitoring task and DAG adherence to time constraints.

affects: Airflow 3.0.0+

gotchaThe `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.

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.

affects: Airflow 3.0.0+

gotchaWhen 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()`.

fix

Update task definitions to import `get_current_context` from `airflow.sdk` and call it within the task function to retrieve the execution context.

affects: Airflow 3.0.0+

Errors

Common errors & fixes

ImportError: cannot import name 'DAG' from 'airflow' (unknown location)

This error occurs when the Python script is named 'airflow.py', causing a conflict with the Airflow package during import.

fix

Rename your script to avoid naming conflicts with the Airflow package.

ImportError: cannot import name 'SUPERVISOR_COMMS' from 'airflow.sdk.execution_time.task_runner'

This error occurs when attempting to import 'SUPERVISOR_COMMS' from 'airflow.sdk.execution_time.task_runner', which may be due to an issue with the Airflow Task SDK.

fix

Ensure you are using the latest version of the Airflow Task SDK and check for any known issues or updates related to this import error.

ModuleNotFoundError: No module named 'my_company'

This error occurs when attempting to import a module from the 'dags' folder without properly configuring the Python path.

fix

Ensure that the 'dags' folder is included in your Python path or use relative imports to access modules within the 'dags' directory.

ModuleNotFoundError: No module named 'your_custom_module'

The Python environment where Airflow is running cannot find the specified module, which can be a custom module within your DAGs folder, a dependency for your tasks, or even the 'apache-airflow-task-sdk' itself if not properly installed.

fix

Ensure the required module is installed in the Airflow environment using `pip install your_custom_module`. If it's a local module, verify its path is correctly added to `PYTHONPATH` or placed in a discoverable location for Airflow's DAG processor.

from airflow.decorators import dag, task

Developers are using the older TaskFlow API decorators from `airflow.decorators`, which are considered internal and less stable, instead of the recommended, forward-compatible interfaces provided by the Apache Airflow Task SDK (`airflow.sdk`).

fix

Update your DAG imports to use the Task SDK namespace: `from airflow.sdk import dag, task`.

Upgrade

Version history

1.3.1latest on PyPI · released Aug 12, 2026

Audit

Dependencies

pythonrequiredRequired Python version for compatibility.

apache-airflowrequiredThe 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.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/apache/airflow ↗

packagehttps://pypi.org/project/apache-airflow-task-sdk/ ↗

homepagehttps://airflow.apache.org/ ↗

docshttps://airflow.apache.org/docs/ ↗