Databricks中Python模块调用dbutils报错，如何转为dbruntime.dbutils.DBUtils？

核心原因 #

pyspark.dbutils.DBUtils是通用Spark环境的轻量实现，未绑定Databricks Runtime的完整上下文，无法正确处理secrets这类需要与Databricks内部服务交互的操作；而dbruntime.dbutils.DBUtils是Databricks Runtime专属实例，包含集群的完整上下文信息。

可行解决方案 #

1. 从Notebook传递dbutils实例到模块（最可靠） #

直接在Notebook调用模块函数时，将当前的dbutils作为参数传入，避免模块自行初始化：

• Notebook代码：

  import your_module
  your_module.your_function(dbutils)
  

• 对应的Python模块代码：

  def your_function(dbutils):
      secret_value = dbutils.secrets.get(scope="your_scope", key="your_key")
      # 后续业务逻辑
  

2. 在模块内通过Databricks Runtime上下文获取实例 #

若必须在模块内部获取dbutils，可直接通过dbruntime模块获取专属实例（仅适用于Databricks Runtime环境）：

from dbruntime.dbutils import DBUtils
from pyspark.sql import SparkSession

def get_dbutils():
    spark = SparkSession.getActiveSession()
    if spark is None:
        raise RuntimeError("未找到活跃的SparkSession")
    return DBUtils(spark)

# 使用示例
dbutils = get_dbutils()
secret_value = dbutils.secrets.get(scope="your_scope", key="your_key")

注意：该方式依赖dbruntime模块，仅在Databricks集群/作业环境中可用，本地开发环境会报错。

3. 解耦模块与secrets操作（最佳实践） #

将secrets的获取逻辑留在Notebook中，模块仅接收解密后的值，降低对Databricks特定API的依赖：

• Notebook代码：

  secret_value = dbutils.secrets.get(scope="your_scope", key="your_key")
  import your_module
  your_module.your_function(secret_value)
  

• 对应的Python模块代码：

  def your_function(secret_value):
      # 使用secret_value处理业务逻辑
  

报错说明 #

IllegalArgumentException: Invalid URI host: null (authority: null)是因为pyspark.dbutils.DBUtils的secrets实现未正确获取Databricks控制平面地址，缺少必要的上下文配置，导致无法发起合法请求。

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