{"id":1084,"library":"apache-airflow-providers-common-compat","title":"Apache Airflow Common Compatibility Provider","description":"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.","status":"active","version":"1.14.2","language":"python","source_language":"en","source_url":"https://github.com/apache/airflow/tree/main/airflow/providers/common/compat","tags":["airflow","provider","compatibility","migration","apache"],"install":[{"cmd":"pip install apache-airflow-providers-common-compat","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core Airflow dependency","package":"apache-airflow","optional":false},{"reason":"ASGI reference implementation, required for certain Python versions.","package":"asgiref","optional":false}],"imports":[{"note":"Use the compatibility layer for version-agnostic imports of core Airflow components in custom providers or plugins.","wrong":"from airflow.models.baseoperator import BaseOperator","symbol":"BaseOperator","correct":"from airflow.providers.common.compat.sdk import BaseOperator"},{"note":"The direct import from `airflow.configuration` is being replaced by the compat SDK for Airflow 3.x compatibility.","wrong":"from airflow.configuration import conf","symbol":"conf","correct":"from airflow.providers.common.compat.sdk import conf"},{"note":"Commonly used for the `@task` decorator in Airflow DAGs and providers for consistency.","symbol":"task","correct":"from airflow.providers.common.compat.sdk import task"}],"quickstart":{"code":"import os\n\n# This example demonstrates how a custom Airflow component (e.g., an operator or hook)\n# would use the common.compat.sdk to ensure compatibility across Airflow versions.\n# In a real scenario, this would typically be part of a custom provider package's code.\n\n# Ensure Airflow environment variables are set for a minimal run, e.g., for 'conf'\n# In a live Airflow environment, these are usually handled by the Airflow setup.\nif 'AIRFLOW_HOME' not in os.environ:\n    os.environ['AIRFLOW_HOME'] = os.path.expanduser('~/airflow')\n\ntry:\n    # Attempt to import common Airflow components via the compatibility layer\n    from airflow.providers.common.compat.sdk import BaseOperator, conf, task\n    print(\"Successfully imported BaseOperator, conf, and task via common.compat.sdk\")\n\n    # Example usage (simplified, as these are typically used within an operator/hook definition)\n    # The actual 'conf' object would be more complex and used for configuration access\n    print(f\"Retrieved BaseOperator from compat layer: {BaseOperator.__name__}\")\n    print(f\"Retrieved conf object from compat layer: {conf}\")\n    print(f\"Retrieved task decorator from compat layer: {task}\")\n\n    # Minimal example of using a compat-imported BaseOperator (not runnable as a full DAG)\n    class MyCompatOperator(BaseOperator):\n        def __init__(self, **kwargs):\n            super().__init__(task_id='my_compat_task', **kwargs)\n\n    my_op_instance = MyCompatOperator()\n    print(f\"Instantiated a custom operator using compat BaseOperator: {my_op_instance.task_id}\")\n\nexcept ImportError as e:\n    print(f\"Failed to import from common.compat.sdk: {e}\")\n    print(\"Ensure 'apache-airflow-providers-common-compat' is installed and Airflow is properly set up.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update provider or plugin code to import `conf` from `airflow.providers.common.compat.sdk`.","message":"Direct 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`.","severity":"breaking","affected_versions":"Airflow 2.11.0+ (in preparation for Airflow 3.x)"},{"fix":"Replace version-specific import logic (e.g., `if AIRFLOW_V_3_0_PLUS:`) with imports from `airflow.providers.common.compat.sdk`.","message":"Custom 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.","severity":"breaking","affected_versions":"All versions when targeting Airflow 3.x compatibility"},{"fix":"Understand that its main value is for library/provider development rather than routine DAG authoring.","message":"This 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure 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.","message":"The `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.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"search_vec":"'1.14.2':73 '2':26,46 '3':29,38 'abstract':48 'adher':82 'aim':54 'airflow':2,9,20,25,28,37,45,67,75,85 'apach':1,8,19,89 'apache-airflow-providers-common-compat':7 'attempt':36 'away':49 'back':43 'cadenc':81 'central':56 'common':3,11 'compat':4,12,16,87 'condit':63 'current':70 'differ':51 'enabl':21 'fall':42 'first':35 'follow':78 'general':77 'import':33,64 'independ':79 'layer':17 'lazi':32 'migrat':23,88 'packag':13 'path':39,47 'provid':5,10,14,53,68,76,86 'releas':80 'replac':58 'scatter':59 'seamless':22 'semver':84 'specif':62 'util':31 'version':50,61,71 'version-specif':60 'within':65","created_at":"2026-04-05T13:05:01.097628+00:00","updated_at":"2026-04-15T20:27:13.627970+00:00","problems":[{"fix":"Install the package using 'pip install apache-airflow-providers-common-compat'.","cause":"The 'apache-airflow-providers-common-compat' package is not installed.","error":"ModuleNotFoundError: No module named 'airflow.providers.common.compat'"},{"fix":"Upgrade to the latest version using 'pip install --upgrade apache-airflow-providers-common-compat'.","cause":"The 'require_provider_version' function is not available in the installed version of 'apache-airflow-providers-common-compat'.","error":"ImportError: cannot import name 'require_provider_version' from 'airflow.providers.common.compat.check'"},{"fix":"Upgrade Apache Airflow to version 2.11.0 or higher.","cause":"The installed version of Apache Airflow is lower than 2.11.0, which is required by the 'apache-airflow-providers-common-compat' package.","error":"RuntimeError: The package `apache-airflow-providers-common-compat:1.12.0` needs Apache Airflow 2.11.0+"},{"fix":"Ensure you are using the correct method to check the version, or refer to the package documentation for version information.","cause":"The '__version__' attribute is not defined in the 'airflow.providers.common.compat' module.","error":"AttributeError: module 'airflow.providers.common.compat' has no attribute '__version__'"},{"fix":"Upgrade Apache Airflow to a version that includes 'AirflowOptionalProviderFeatureException', or check the documentation for the correct import path.","cause":"The 'AirflowOptionalProviderFeatureException' class is not available in the installed version of Apache Airflow.","error":"ImportError: cannot import name 'AirflowOptionalProviderFeatureException' from 'airflow.exceptions'"}],"ecosystem":"pypi","meta_description":null,"install_score":75,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.15.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/apache/airflow","docs":"https://airflow.apache.org/docs/apache-airflow-providers-common-compat/1.14.3","changelog":"https://airflow.apache.org/docs/apache-airflow-providers-common-compat/1.14.3/changelog.html","pypi":"https://pypi.org/project/apache-airflow-providers-common-compat/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["workflow","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"reviewed"}}