Registry /
workflow / apache-airflow-providers-common-compat
The `apache-airflow-providers-common-compat` package provides a compatibility layer for Apache Airflow, enabling seamless migration from Airflow 2 to Airflow 3. It utilizes lazy imports that first attempt Airflow 3 paths and then fall back to Airflow 2 paths, abstracting away version differences. This provider aims to centralize and replace scattered version-specific conditional imports within other Airflow providers. The current version is 1.14.2, and Airflow providers generally follow independent release cadences, adhering to SemVer.
Install & Compatibility
Where this runs
tested against v1.15.0 · 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
260MB installed
● package 260MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BaseOperator
✓ from airflow.providers.common.compat.sdk import BaseOperator
✗ from airflow.models.baseoperator import BaseOperator
Use the compatibility layer for version-agnostic imports of core Airflow components in custom providers or plugins.
conf
✓ from airflow.providers.common.compat.sdk import conf
✗ from airflow.configuration import conf
The direct import from `airflow.configuration` is being replaced by the compat SDK for Airflow 3.x compatibility.
task
✓ from airflow.providers.common.compat.sdk import task
Commonly used for the `@task` decorator in Airflow DAGs and providers for consistency.
This quickstart demonstrates how a developer building a custom Airflow provider or plugin would use `airflow.providers.common.compat.sdk` to import core Airflow components like `BaseOperator`, `conf`, or `@task` in a way that is compatible across different major versions of Apache Airflow (e.g., Airflow 2.x and 3.x). This code snippet shows successful imports and basic instantiation of a class using `BaseOperator` obtained from the compatibility layer.
import os
# This example demonstrates how a custom Airflow component (e.g., an operator or hook)
# would use the common.compat.sdk to ensure compatibility across Airflow versions.
# In a real scenario, this would typically be part of a custom provider package's code.
# Ensure Airflow environment variables are set for a minimal run, e.g., for 'conf'
# In a live Airflow environment, these are usually handled by the Airflow setup.
if 'AIRFLOW_HOME' not in os.environ:
os.environ['AIRFLOW_HOME'] = os.path.expanduser('~/airflow')
try:
# Attempt to import common Airflow components via the compatibility layer
from airflow.providers.common.compat.sdk import BaseOperator, conf, task
print("Successfully imported BaseOperator, conf, and task via common.compat.sdk")
# Example usage (simplified, as these are typically used within an operator/hook definition)
# The actual 'conf' object would be more complex and used for configuration access
print(f"Retrieved BaseOperator from compat layer: {BaseOperator.__name__}")
print(f"Retrieved conf object from compat layer: {conf}")
print(f"Retrieved task decorator from compat layer: {task}")
# Minimal example of using a compat-imported BaseOperator (not runnable as a full DAG)
class MyCompatOperator(BaseOperator):
def __init__(self, **kwargs):
super().__init__(task_id='my_compat_task', **kwargs)
my_op_instance = MyCompatOperator()
print(f"Instantiated a custom operator using compat BaseOperator: {my_op_instance.task_id}")
except ImportError as e:
print(f"Failed to import from common.compat.sdk: {e}")
print("Ensure 'apache-airflow-providers-common-compat' is installed and Airflow is properly set up.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingDirect imports from `airflow.configuration` for the `conf` object are being deprecated. For Airflow 3.x compatibility, it is recommended to replace `from airflow.configuration import conf` with `from airflow.providers.common.compat.sdk import conf`.fixUpdate provider or plugin code to import `conf` from `airflow.providers.common.compat.sdk`.
affects: Airflow 2.11.0+ (in preparation for Airflow 3.x)
breakingCustom Airflow providers or plugins that currently use local `version_compat.py` files or version-specific conditional imports should migrate to use the `airflow.providers.common.compat.sdk` layer. This is a recommended architectural change for seamless Airflow 3.x compatibility.fixReplace version-specific import logic (e.g., `if AIRFLOW_V_3_0_PLUS:`) with imports from `airflow.providers.common.compat.sdk`.
affects: All versions when targeting Airflow 3.x compatibility
gotchaThis provider is primarily intended for *Apache Airflow provider developers* to write version-agnostic code for their custom components (Operators, Hooks, Sensors, etc.). While end-users writing DAGs *could* technically use it for custom tasks or modules, its main purpose is to centralize and abstract compatibility logic for the broader provider ecosystem, not typically for direct DAG definitions.fixUnderstand that its main value is for library/provider development rather than routine DAG authoring.
affects: All
breakingThe `airflow.providers.common.compat.sdk` module could not be imported, indicating that the `apache-airflow-providers-common-compat` package might not be installed or Airflow is not properly set up in the environment. This library is a crucial dependency for using the compatibility layer features.fixEnsure that the `apache-airflow-providers-common-compat` package is installed (e.g., `pip install apache-airflow-providers-common-compat`) and that Airflow is properly set up in the environment where the code is being run.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'airflow.providers.common.compat'
The 'apache-airflow-providers-common-compat' package is not installed.
fixInstall the package using 'pip install apache-airflow-providers-common-compat'.
ImportError: cannot import name 'require_provider_version' from 'airflow.providers.common.compat.check'
The 'require_provider_version' function is not available in the installed version of 'apache-airflow-providers-common-compat'.
fixUpgrade to the latest version using 'pip install --upgrade apache-airflow-providers-common-compat'.
RuntimeError: The package `apache-airflow-providers-common-compat:1.12.0` needs Apache Airflow 2.11.0+
The installed version of Apache Airflow is lower than 2.11.0, which is required by the 'apache-airflow-providers-common-compat' package.
fixUpgrade Apache Airflow to version 2.11.0 or higher.
AttributeError: module 'airflow.providers.common.compat' has no attribute '__version__'
The '__version__' attribute is not defined in the 'airflow.providers.common.compat' module.
fixEnsure you are using the correct method to check the version, or refer to the package documentation for version information.
ImportError: cannot import name 'AirflowOptionalProviderFeatureException' from 'airflow.exceptions'
The 'AirflowOptionalProviderFeatureException' class is not available in the installed version of Apache Airflow.
fixUpgrade Apache Airflow to a version that includes 'AirflowOptionalProviderFeatureException', or check the documentation for the correct import path.
Audit
Dependencies
apache-airflowrequiredCore Airflow dependency
asgirefrequiredASGI reference implementation, required for certain Python versions.