Airflow Docker部署遇ModuleNotFoundError：scripts模块无法导入

在Docker环境运行Airflow项目时，持续遇到ModuleNotFoundError，代码尝试从scripts目录导入函数时失败，报错信息如下：

Broken DAG: [/opt/airflow/dags/transport_etl_dag.py] Traceback (most recent call last):
File "", line 219, in _call_with_frames_removed
File "/opt/airflow/dags/transport_etl_dag.py", line 7, in
from scripts.utensils import get_snowpark_session
ModuleNotFoundError: No module named 'scripts'

项目结构：

root  
dags:
  transport_etl_dag.py
  transport_etl_tasks.py  
scripts:
  __init__.py
  utensils.py  
dockerfile  
docker-compose  
docker-entrypoint  
requirements.txt  

已尝试配置PYTHONPATH，在scheduler容器终端执行echo $PYTHONPATH显示:/opt/airflow/scripts，目录文件均存在，但问题未解决。

• 调整PYTHONPATH指向父目录
  Python查找模块时，需要的是包含目标模块目录的路径，而非模块目录本身。当前PYTHONPATH设为/opt/airflow/scripts，Python会在该目录下寻找scripts模块，自然找不到。应将PYTHONPATH改为/opt/airflow，让Python能识别到scripts这个模块目录。
  在docker-compose.yml的scheduler和worker服务中添加环境变量配置：

  environment:
    - PYTHONPATH=/opt/airflow
  

  或者在Dockerfile中设置：

  ENV PYTHONPATH="/opt/airflow"
  

• 验证目录挂载与权限
  确认本地scripts目录已正确挂载到容器的/opt/airflow/scripts路径，在容器终端执行：

  ls /opt/airflow/scripts
  

  检查是否存在__init__.py和utensils.py，同时确保Airflow运行用户（默认是airflow）对这些文件有读取权限：

  ls -l /opt/airflow/scripts
  

• 临时修复：动态添加路径到sys.path
  如果环境变量配置暂时无法生效，可在transport_etl_dag.py开头添加代码，将项目根目录加入Python路径：

  import sys
  from pathlib import Path
  
  # 获取项目根目录（dags的父目录）
  project_root = Path(__file__).parent.parent
  sys.path.append(str(project_root))
  
  from scripts.utensils import get_snowpark_session
  

• 检查__init__.py文件
  确保scripts/__init__.py文件为空或无语法错误，若该文件存在问题，会导致Python无法识别scripts为有效模块。

• 确认Airflow进程加载了正确的环境变量
  有时终端手动设置的PYTHONPATH不会同步到Airflow的scheduler/worker进程，需通过docker-compose或Dockerfile配置环境变量，确保进程启动时能读取到正确的PYTHONPATH。可以在容器内查看Airflow进程的环境变量：

  # 找到scheduler进程ID
  ps aux | grep airflow-scheduler
  # 查看进程环境变量，替换为实际PID
  cat /proc/<PID>/environ | tr '\0' '\n' | grep PYTHONPATH
  

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