如何使用Databricks Asset Bundles导入本地模块并解决导入错误？

问题背景 #

项目结构、配置及执行流程如下：

项目目录结构 #

databricks.yml
src/
├── __init__.py
└── jobs
    ├── __init__.py
    ├── bronze
    │   └── my_script.py
    └── common.py

Databricks Bundle配置 (databricks.yml) #

bundle:
  name: my_bundle

workspace:
  host: XXX

targets:
  dev:
    mode: development
    default: true

resources:
  jobs:
    my_job:
      name: my_job
      tasks:
        - task_key: my_task
          existing_cluster_id: YYY
          spark_python_task:
            python_file: src/jobs/bronze/my_script.py

执行流程 #

使用Databricks CLI v0.206.0执行以下命令部署并运行任务：

databricks bundle validate
databricks bundle deploy
databricks bundle run my_job

报错信息 #

执行时触发ModuleNotFoundError: No module named 'src'，尝试多种导入写法（from src.jobs.common import *、from jobs.common import *等）均无效。

解决方案 #

方法1：在脚本中手动注入项目根路径 #

在my_script.py开头添加代码，将项目根目录（包含src的目录）加入Python搜索路径，确保解释器能找到src模块：

import sys
from pathlib import Path

# 回溯到项目根目录（当前脚本路径：src/jobs/bronze/my_script.py → 向上三级到根）
project_root = Path(__file__).parent.parent.parent
sys.path.append(str(project_root))

from src.jobs.common import hello_world

if __name__ == "__main__":
    hello_world()

方法2：通过Bundle配置上传整个源码目录 #

修改databricks.yml的任务配置，添加source字段指定要上传到集群的源码目录，这样集群上的执行环境会包含整个src目录：

resources:
  jobs:
    my_job:
      name: my_job
      tasks:
        - task_key: my_task
          existing_cluster_id: YYY
          spark_python_task:
            python_file: src/jobs/bronze/my_script.py
          # 新增source字段，上传整个src目录到集群
          source: src/

此时可以简化导入语句为：

from jobs.common import hello_world

方法3：使用相对导入（需配合路径调整） #

如果偏好相对导入，可调整脚本中的导入语句，但需确保执行上下文的工作目录正确：

from ..common import hello_world

注意：单独使用相对导入可能因集群执行时的工作目录与本地不一致而失效，建议结合方法1的路径注入一起使用。

方法4：打包为Python Wheel（适合复杂项目） #

若项目模块较多，可将src目录打包成Python Wheel包，通过Bundle部署到工作区后在集群安装：

1. 在项目根目录编写pyproject.toml定义包信息：

   [build-system]
   requires = ["setuptools>=61.0"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "my_databricks_jobs"
   version = "0.1.0"
   packages = ["src"]
   

2. 修改databricks.yml添加Wheel资源：

   resources:
    wheels:
      my_job_wheel:
        path: .
        build: true
    jobs:
      my_job:
        name: my_job
        tasks:
          - task_key: my_task
            existing_cluster_id: YYY
            spark_python_task:
              python_file: src/jobs/bronze/my_script.py
            libraries:
              - wheel: {{ resources.wheels.my_job_wheel.path }}
   

3. 重新部署后，集群会自动安装该Wheel，此时可直接使用from src.jobs.common import ...导入模块。

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