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
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
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.fixEnsure 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.fixCheck 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`.fixIt 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.fixDouble-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.
fixUninstall `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.
fixEnsure 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.
fixVerify 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.
fixEnsure 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.
fixExamine 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.