安装适用于 Python 的 Databricks Connect

2025-06-16

注意

本文介绍适用于 Databricks Runtime 13.3 LTS 及更高版本的 Databricks Connect。

本文介绍如何安装或更新适用于 Python 的 Databricks Connect。请参阅什么是 Databricks Partner Connect？。有关本文的 Scala 版本，请参阅安装适用于 Scala 的 Databricks Connect。

要求

要安装适用于 Python 的 Databricks Connect，必须满足以下要求：

如果要连接到群集，则目标群集必须满足群集配置要求，其中包括 Databricks Runtime 版本要求。
必须已在开发计算机上安装 Python 3，并且开发计算机上安装的 Python 次要版本必须满足下表中的版本要求。
如果使用用户定义的函数（UDF），则 Python 的本地次要版本必须与群集或无服务器计算的 Databricks Runtime 版本的 Python 的次要版本匹配。若要查找群集的 Databricks Runtime 版本的次要 Python 版本，请参阅该版本的 Databricks Runtime 发行说明的“系统环境”章节。请参阅 Databricks Runtime 发行说明版本和兼容性。

版本支持矩阵

下表显示了兼容的 Databricks Connect 和 Python 版本。 Databricks Connect 版本号对应于 Databricks Runtime 版本号。

计算类型	Databricks Connect 版本	兼容的 Python 版本
集群	16.0 及更高版本	3.12
集群	15.4 LTS	3.11
集群	13.3 LTS 到 14.3 LTS	3.10

激活 Python 虚拟环境

Databricks 强烈建议为与 Databricks Connect 配合使用的每个 Python 版本激活 Python 虚拟环境。 Python 虚拟环境有助于确保将正确版本的 Python 和 Databricks Connect 一起使用。有关这些工具及其激活方式的详细信息，请参阅venv或Poetry。

安装 Databricks Connect 客户端

本部分介绍了如何使用venv或Poetry安装 Databricks Connect 客户端。

注意

如果已安装适用于 Visual Studio Code 的 Databricks 扩展，则无需按照这些设置说明进行操作，因为适用于 Visual Studio Code 的 Databricks 扩展已内置支持适用于 Databricks Runtime 13.3 LTS 及更高版本的 Databricks Connect。跳过使用 Databricks Connect 为 Visual Studio Code 的 Databricks 扩展调试代码。

使用 vnev 安装 Databricks Connect 客户端

激活虚拟环境后，运行 uninstall 命令卸载 PySpark（如果已安装）。这是必需的，因为 databricks-connect 包与 PySpark 冲突。有关详细信息，请参阅 PySpark 安装存在冲突。若要检查是否已安装 PySpark，请运行 show 命令。
```
# Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark
```
在虚拟环境仍处于激活状态的情况下，运行 install 命令安装 Databricks Connect 客户端。使用 --upgrade 选项将任何现有客户端安装升级到指定的版本。
```
pip3 install --upgrade "databricks-connect==15.4.*"  # Or X.Y.* to match your cluster version.
```
注意

Databricks 建议追加“.*”符号来指定 databricks-connect==X.Y.* 而不是 databricks-connect=X.Y，以确保安装最新的包。虽然并不要求如此，但这样有助于确保为该群集使用最新的受支持功能。

使用 Poetry 安装 Databricks Connect 客户端

激活虚拟环境后，运行 remove 命令卸载 PySpark（如果已安装）。这是必需的，因为 databricks-connect 包与 PySpark 冲突。有关详细信息，请参阅 PySpark 安装存在冲突。若要检查是否已安装 PySpark，请运行 show 命令。
```
# Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark
```
在虚拟环境仍处于激活状态的情况下，运行 add 命令安装 Databricks Connect 客户端。
```
poetry add databricks-connect@~15.4  # Or X.Y to match your cluster version.
```
注意

Databricks 建议使用“at-tilde”表示法来指定 databricks-connect@~15.4 而不是 databricks-connect==15.4，以确保安装最新的包。虽然并不要求如此，但这样有助于确保为该群集使用最新的受支持功能。

后续步骤

安装 Databricks Connect 后，需要配置与 Databricks 的连接。请参阅 Databricks Connect 的计算配置。

共用方式為