Airflow提交Databricks任务安装本地.whl文件报错排查

核心认知澄清 #

Databricks 确实支持本地路径whl安装，你遇到的两个问题都是路径认知和集群库安装机制理解偏差导致的：

1. file:/ 前缀指向的不是Airflow运行服务器的本地文件系统，而是Databricks集群工作节点的本地文件系统。你把whl放在Airflow所在机器的本地路径下，集群节点上根本不存在对应文件，自然会抛出fileNotFound异常。只有当你提前把whl分发到集群所有节点的相同本地路径下，这个前缀的路径才会生效。
2. 不带前缀的路径不符合Databricks API的URI格式要求，所以会触发你看到的前缀校验报错。

DBFS路径安装卡pending的常见原因 #

走DBFS路径安装卡pending基本都是以下几个原因，按出现概率排序：

• 你使用的是固定的现有集群（existing_cluster_id），如果集群上有正在运行的其他作业，Databricks的全局库安装逻辑会等待所有运行中任务结束、集群进入空闲状态才会执行安装，只要集群一直有任务占用，就会一直卡在pending状态。
• DBFS路径权限不足：存放whl的DBFS路径没有给集群绑定的服务账号/访问用户开放读权限，部分版本的Databricks不会直接抛出权限错误，只会卡在pending状态。
• whl包兼容性问题：whl包的编译平台、Python版本、依赖版本和集群运行环境不匹配，安装进程挂起无响应。
• 路径选择问题：把whl放在DBFS临时目录（如dbfs:/tmp）下，文件被生命周期规则自动清理，导致安装进程找不到源文件。

可落地的解决方法 #

按落地复杂度从低到高推荐：

• 优先选任务级安装（最适配Airflow调度场景）：不要在libraries参数中声明whl依赖，先在Airflow中前置一个步骤把本地whl上传到DBFS自定义路径（如dbfs:/FileStore/jars/custom_libs/），然后在作业逻辑的第一行添加pip安装命令，以Notebook任务为例：

# 任务开头先执行安装
%pip install /dbfs/FileStore/jars/custom_libs/your_package-0.1.0-py3-none-any.whl
dbutils.library.restartPython()

# 后续写业务逻辑

这种安装是任务级隔离的，不需要等待集群空闲，不会出现全局pending的问题，也不会影响集群上运行的其他作业。

• 如果一定要用libraries参数传DBFS路径的whl：先手动重启目标现有集群，集群重启完成后第一时间触发Airflow任务，避免集群上堆积其他作业，即可正常完成安装。
• 如果必须用file:/本地路径：编写集群init脚本，在节点启动时把DBFS上存储的whl提前拷贝到所有节点的统一本地目录（如/opt/custom_libs/），再在libraries参数中填写对应本地路径即可。

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