Airflow自定义Hook/Operator报错：ModuleNotFoundError: No module named 'plugins'

在Airflow 2.6.3版本中创建自定义Hook和Operator时，出现模块找不到错误：

Broken DAG: [/opt/airflow/dags/test_dag.py] Traceback (most recent call last):
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/opt/airflow/dags/test_dag.py", line 9, in <module>
    from plugins.operators.synapse import AzureSynapseRunPipelineOperator
ModuleNotFoundError: No module named 'plugins'

项目目录结构：

my-git-repo/
├── dags/
│   ├── test_dag.py
├── plugins/
│   ├── __init__.py
│   ├── hooks/
│   │   ├── __init__.py
│   │   ├── synapse.py
│   ├── operators/
│   │   ├── __init__.py
│   │   ├── synapse.py (contains AzureSynapseRunPipelineOperator)

test_dag.py中的导入语句：

from plugins.operators.synapse import AzureSynapseRunPipelineOperator

测试环境：本地Airflow Docker镜像、Azure托管Airflow实例，均出现同类报错。

1. 确认插件目录挂载/配置 #

Airflow默认将$AIRFLOW_HOME/plugins目录加入Python路径，需确保你的plugins目录被正确部署：

• Docker环境：检查docker-compose.yml中是否包含plugins目录的挂载配置：

  volumes:
    - ./dags:/opt/airflow/dags
    - ./plugins:/opt/airflow/plugins  # 必须存在这一行
  

• Azure托管Airflow：在Azure门户的Airflow实例配置中，确认Git仓库同步时，plugins目录被放置到Airflow的默认插件路径下（Azure托管Airflow通常自动识别仓库根目录的plugins目录，若路径异常需调整同步规则）。

2. 修正导入语句 #

Airflow会自动将插件目录加入Python路径，导入时无需带上plugins前缀。修改test_dag.py的导入语句：

from operators.synapse import AzureSynapseRunPipelineOperator

3. 验证包结构完整性 #

确保所有目录下的__init__.py文件存在：

• plugins/__init__.py、plugins/hooks/__init__.py、plugins/operators/__init__.py必须存在，否则Python无法识别这些目录为可导入包。
• 若想简化导入，可在plugins/operators/__init__.py中添加导出逻辑：

  from .synapse import AzureSynapseRunPipelineOperator
  

  之后导入可简化为：from operators import AzureSynapseRunPipelineOperator

4. 重启Airflow服务 #

修改插件或配置后，需重启Airflow服务使其生效：

• Docker环境：执行命令 docker-compose restart webserver scheduler
• Azure托管Airflow：在Azure门户中重启Airflow实例，或等待Git同步完成后服务自动刷新。

内容的提问来源于stack exchange，提问作者csukcl