Apache Airflow Best Practices (3.2.0)

DAG Authoring

Imports (Airflow 3.x)

• Use from airflow.sdk import DAG, task, Asset — the stable public API
• Legacy from airflow.models import DAG and from airflow.decorators import task are deprecated

Top-Level Code (CRITICAL)

• Avoid heavy computation at module level (executed on every DAG parse)
• Minimize imports at module level — lazy-load inside @task functions
• Never call APIs, query databases, or access Variables at top level
• If Variables needed at top level, enable experimental cache with TTL

TaskFlow API (Default Pattern)

• Use @task decorator for all Python tasks (preferred over classic operators)
• XCom serialization is automatic — return values become XCom
• Use @task.branch for branching logic
• Use @task.sensor for sensor tasks