Registry / database / databricks-connect

databricks-connect

JSON →
library19.1pypypi✓ verified 27d ago

Databricks Connect allows you to connect popular IDEs, notebook servers, and custom applications to Databricks clusters. It's a client library that configures standard PySpark APIs to run commands remotely on Databricks clusters, enabling local development and debugging against data on a remote cluster. The current version is 18.1.2, with releases tied closely to Databricks Runtime (DBR) versions, typically aligning with DBR major/LTS releases and subsequent patch updates.

pip install databricks-connect==18.1.2
INSTALL
IMPORT
SIG · DATABRICKS-CONNECT
D
databricks-connect
databasepythonv19.1
Install
15.1s avg
Import
875ms
Disk
459MB
Pass rate
2/ 10
Env Coverage2 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v18.1.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.12
✓ —
✓ 15.1s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
459MB installed
● package 459MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SparkSession
from pyspark.sql import SparkSession
from databricks.connect import SparkSession
Databricks Connect configures the standard PySpark SparkSession, you don't import SparkSession directly from databricks.connect.

This quickstart demonstrates how to initialize a SparkSession with Databricks Connect using environment variables for configuration. Ensure your `DATABRICKS_HOST`, `DATABRICKS_TOKEN`, and `DATABRICKS_CLUSTER_ID` are set correctly. The `display()` command requires a Databricks environment; use `show()` for local console output.

import os from pyspark.sql import SparkSession # Configure environment variables (replace with your actual values) # For DBR 13.x and later, DATABRICKS_CLUSTER_ID is required. # For DBR 12.x and earlier, DATABRICKS_ORG_ID might be required. # DATABRICKS_PORT is optional, defaults to 15001. os.environ['DATABRICKS_HOST'] = os.environ.get('DATABRICKS_HOST', 'https://your-databricks-instance.cloud.databricks.com') os.environ['DATABRICKS_TOKEN'] = os.environ.get('DATABRICKS_TOKEN', 'dapi...') os.environ['DATABRICKS_CLUSTER_ID'] = os.environ.get('DATABRICKS_CLUSTER_ID', 'your-cluster-id') # os.environ['DATABRICKS_ORG_ID'] = os.environ.get('DATABRICKS_ORG_ID', 'your-org-id') # Often not needed for modern DBR/configurations # os.environ['DATABRICKS_PORT'] = os.environ.get('DATABRICKS_PORT', '15001') # Default is 15001 # Initialize SparkSession using Databricks Connect # The .builder.getOrCreate() method automatically picks up DATABRICKS_ environment variables. spark = SparkSession.builder.getOrCreate() # Example: Run a simple Spark command df = spark.range(10).toDF("id") df.display() # df.show() # For local console output print("Successfully connected to Databricks cluster and ran a Spark command.") # Clean up environment variables if running multiple tests or configurations # del os.environ['DATABRICKS_HOST'] # del os.environ['DATABRICKS_TOKEN'] # del os.environ['DATABRICKS_CLUSTER_ID'] # (and others you set)
databricks-connect --version
Debug
Known issues
breakingDatabricks Connect client versions are strictly tied to specific Python versions. For instance, Databricks Connect 18.x requires Python 3.12. Using an incompatible Python version will result in installation failures or runtime errors.
fix
Ensure your local Python environment's major and minor version exactly matches the requirement for your Databricks Connect client version (e.g., Python 3.12 for databricks-connect==18.x).
affects: All versions, specifically 18.x and later for Python 3.12
breakingThe Databricks Connect client version must exactly match the Databricks Runtime (DBR) version of the cluster you are connecting to. Mismatched versions will lead to connection errors or unexpected behavior.
fix
Check your cluster's DBR version and install the corresponding `databricks-connect` client version (e.g., for DBR 13.3 LTS, install `databricks-connect==13.3.*`).
affects: All versions
gotchaInstalling `databricks-connect` with an existing `pyspark` installation can lead to dependency conflicts or unexpected `pyspark` version mismatches. `databricks-connect` bundles its own compatible `pyspark`.
fix
It is highly recommended to install `databricks-connect` in a clean Python virtual environment. Do not install `pyspark` separately when using `databricks-connect`.
affects: All versions
gotchaIncorrect configuration of connection parameters (host, token, cluster ID, sometimes org ID or port) is a very common reason for connection failures.
fix
Double-check that `DATABRICKS_HOST`, `DATABRICKS_TOKEN`, and `DATABRICKS_CLUSTER_ID` environment variables (or values passed directly to SparkSession builder) are correct and correspond to your target Databricks cluster and workspace. Ensure your token has sufficient permissions.
affects: All versions
Errors
Common errors & fixes
The databricks-connect package conflicts with PySpark.
The `databricks-connect` library and the open-source `pyspark` library cannot coexist in the same Python environment because they both provide Spark client functionalities, leading to conflicts during Spark context initialization.
fix
Uninstall `pyspark` from your local environment before installing or reinstalling `databricks-connect`. It is recommended to use a dedicated Python virtual environment for Databricks Connect.
java.lang.IllegalArgumentException: The cluster is running server version `dbr-X.Y` but this client only supports Set(dbr-A.B)
This error occurs when the version of the `databricks-connect` client library installed locally does not precisely match the Databricks Runtime (DBR) version of the remote cluster you are trying to connect to.
fix
Ensure that your local `databricks-connect` package version exactly matches the major and minor version of your Databricks cluster's runtime (e.g., for DBR 18.1.2, use `databricks-connect==18.1.*`). You might need to update or downgrade your `databricks-connect` installation using `pip install --upgrade 'databricks-connect==X.Y.*'`.
StatusCode.UNAVAILABLE, StatusCode.UNKNOWN, DNS resolution failed, or Received http2 header with status: 500
These errors indicate that the local machine running `databricks-connect` cannot establish a proper network connection to the Databricks cluster, often due to incorrect configuration parameters (workspace URL, cluster ID), network issues, or firewall restrictions.
fix
Verify that your Databricks workspace instance name and cluster ID are correctly configured (e.g., in `~/.databrickscfg` or environment variables). Check local network connectivity, DNS resolution, and ensure that no firewalls are blocking communication to the Databricks control plane.
ModuleNotFoundError: No module named 'your_module_name'
When running code with `databricks-connect`, Python code (including imports) is executed on your local machine, while Spark operations are sent to the remote cluster. If a custom module or a required third-party library is only installed on the remote cluster or is not in your local Python environment's path, it will not be found.
fix
Ensure that all custom Python modules and necessary third-party libraries used in your local code are also installed in the Python environment where `databricks-connect` is running. For custom modules, make sure they are accessible via your Python path.
Py4JJavaError
A generic `Py4JJavaError` indicates an error occurred within the Java Virtual Machine (JVM) on the Databricks cluster, often caused by issues such as out-of-memory (OOM) errors during data processing, incompatible data types, serialization problems, or other runtime exceptions in Spark operations.
fix
Examine the full stack trace for more specific details about the Java exception. Common solutions include checking for Python/PySpark version compatibility, optimizing Spark code for memory usage (e.g., reducing `collect()` on large DataFrames), ensuring data types are consistent, and verifying cluster resources.
Upgrade
Version history
19.1latest on PyPI · released Aug 14, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
45 hits · last 30 days
node
34
OpenAI (training)
2
Resources
databricks-connect — pip install databricks-connect · libregistry