Airflow Plugin Compatibility: Supported Airflow Versions and Extra Dependencies – DataHub Customer Support Portal

Area: Ingestion Issues

Sub-Area: Airflow Plugin Version Compatibility

Issue

Users running acryl-datahub-airflow-plugin on Apache Airflow versions outside the explicitly documented compatibility matrix — particularly Airflow 2.11.x — may encounter silent lineage capture failures, DAG/task metadata emission problems, or scheduler hook errors. A common source of these failures is using the wrong installation extra for the target Airflow runtime: specifically, installing the [airflow3] extra against an Airflow 2.x environment. Because the plugin's version constraints allow pip to resolve and install without error, the incompatibility is not immediately obvious at install time.

You Might Be Asking

Is acryl-datahub-airflow-plugin compatible with Airflow 2.11.x?
Which plugin extra should I use — [airflow2] or [airflow3] — for my Airflow version?
Why is lineage not being captured even though the plugin installed without errors?
What versions of apache-airflow-providers-openlineage are compatible with Airflow 2.x vs. Airflow 3.x?
What is the supported upgrade path now that Airflow 2.x support has been dropped from the plugin?

Error Messages

No lineage emitted for DAG runs
AttributeError or ImportError related to Airflow internal APIs at runtime
Silent non-emission of DAG/task metadata to DataHub (no explicit error, but no data appearing)

Solution

Follow the steps below to identify your situation and apply the correct resolution.

Confirm the supported compatibility matrix.

The official tested compatibility ladder for acryl-datahub-airflow-plugin is:

Airflow Version	Plugin Version	Correct Extra
2.7 – 2.10	`acryl-datahub-airflow-plugin <= 1.6.0`	`[airflow2]`
3.0+	Current / latest release	`[airflow3]`

Airflow 2.11.x is not listed because it was never part of the tested CI matrix. The highest Airflow 2.x version ever validated was 2.10.x. Airflow 2.11.x may be largely API-compatible with 2.10 at the Python level, but correctness of lineage capture, scheduler hooks, and DataHub emission on this version cannot be guaranteed.

Understand the [airflow3] extra and why it breaks on Airflow 2.x.
In plugin versions up to 1.4.0, the [airflow3] extra is defined without an upper bound:
```
"airflow3": ["apache-airflow-providers-openlineage>=1.0.0"]
```
Without a version cap, pip resolves this to the latest available release of apache-airflow-providers-openlineage (2.x at the time of writing). The 2.x line of this provider was designed for Apache Airflow 3.x. Running it against an Airflow 2.x runtime is an unsupported combination and is the most likely cause of lineage capture failures or silent non-emission — even if installation completes without errors.

The [airflow2] extra installs openlineage-airflow>=1.2.0, which is the correct OpenLineage package for Airflow 2.x environments.
Choose a remediation path.
Option A — Upgrade to Airflow 3.x (recommended):

This is the fully supported path. Upgrade your Airflow environment to 3.0+ and install the latest plugin release:
```
pip install "acryl-datahub-airflow-plugin[airflow3]"
```
Option B — Stay on Airflow 2.x and pin the OpenLineage provider to the 1.x line:

If upgrading to Airflow 3 is not immediately feasible and you must remain on an Airflow 2.x version, explicitly cap the OpenLineage provider to avoid resolving the Airflow-3-targeted 2.x package:
```
pip install \
  "acryl-datahub-airflow-plugin==1.4.0" \
  "apache-airflow-providers-openlineage>=1.0.0,<2.0.0"
```
Note: If you are on Airflow 2.11.x, this combination remains untested. You may encounter edge-case issues with DAG serialization or listener hooks introduced between Airflow 2.10 and 2.11. This path carries no correctness guarantee from the DataHub team.

Option C — Downgrade to plugin 1.6.0 with proper Airflow 2.x extras:

Plugin version 1.6.0 was the last release that officially targeted Airflow 2.x. Use it with the pinned OpenLineage provider:
```
pip install \
  "acryl-datahub-airflow-plugin[airflow2]==1.6.0" \
  "apache-airflow-providers-openlineage>=1.0.0,<2.0.0"
```
This still carries the caveat that Airflow 2.11.x was not part of the Airflow 2 test matrix. The highest tested Airflow 2.x version was 2.10.x.
Verify lineage emission after applying the fix.
After reinstalling with the correct extra and pinned provider, trigger a test DAG run and confirm that lineage events appear in DataHub. You can use the DataHub CLI to check for recent ingestion activity:
```
datahub ingest list-runs
```
Alternatively, navigate to the DataHub UI and search for the dataset or pipeline entity associated with your test DAG to confirm metadata and lineage are being captured.

Additional Notes

As of June 2026, Airflow 2.x support has been officially removed from the DataHub Airflow plugin. The base requirement for current plugin releases is apache-airflow>=3.0.0,<4.0.0. Users still on any Airflow 2.x version — including 2.10.x — should plan an upgrade to Airflow 3.x to remain on a supported integration path. Plugin versions 1.6.0 and below remain available for Airflow 2.7–2.10 users who cannot immediately upgrade, but these versions will not receive new features or bug fixes. Airflow 2.11.x was never an explicitly supported version and falls outside both the Airflow 2.x and Airflow 3.x support windows for this plugin.

Issue

You Might Be Asking

Error Messages

Solution

Additional Notes

Related Documentation