Apache Airflow Mypy plugins¶

apache-airflow-mypy provides mypy plugins for Airflow-specific patterns. The package is optional, independently versioned, and is not required to run Airflow.

Use the plugins when type-checking Dags, custom operators, or hooks to avoid false positives that plain mypy cannot resolve. The plugins support:

Typed decorators – decorators that inject keyword arguments at runtime, such as GoogleBaseHook.fallback_to_default_project_id.
Operator outputs – the .output attribute of operators and the return value of @task-decorated functions are resolved from XComArg to their underlying runtime type.

Installation¶

Install the package alongside mypy:

pip install apache-airflow-mypy

The package follows SemVer and can be upgraded independently of Airflow.

Configuration¶

Enable both plugins in mypy.ini, setup.cfg, or pyproject.toml:

[mypy]
plugins = airflow_mypy.plugins.decorators, airflow_mypy.plugins.outputs

For example, the output plugin lets mypy infer the return type of a TaskFlow task:

@task
def count_characters(value: str) -> int:
    return len(value)


@task
def report_count(count: int) -> None: ...


report_count(count_characters("Airflow"))

Without the plugin, mypy sees an XComArg passed to report_count. With the plugin enabled, it understands that count_characters produces an int.