Install & Compatibility
Where this runs
tested against v3.30.1 · 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
✓ 2.7s
py 3.11
✕ build_error
✓ 2.5s
py 3.12
✕ build_error
✓ 2.4s
py 3.13
✕ build_error
✓ 2.3s
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Cluster
✓ from cassandra.cluster import Cluster
PlainTextAuthProvider
✓ from cassandra.auth import PlainTextAuthProvider
ConsistencyLevel
✓ from cassandra import ConsistencyLevel
BatchStatement
✓ from cassandra.query import BatchStatement
This quickstart connects to a local Cassandra instance (at 127.0.0.1), creates a keyspace and table if they don't exist, inserts a row, and then queries data. For production environments or Astra DB, `contact_points` should be set to your cluster's actual endpoints, and `PlainTextAuthProvider` should be used with credentials (e.g., from environment variables) for secure connections. Ensure `Cluster` and `Session` objects are properly shut down to release resources.
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider # For secure connections
import os
# For local Cassandra, 'contact_points' can be ['127.0.0.1']
# For Astra DB or secure clusters, specify contact_points and auth_provider
# using credentials from environment variables.
# Example: CONTACT_POINTS = ['your.cassandra.host']
# ASTRA_CLIENT_ID = os.environ.get('ASTRA_CLIENT_ID', '')
# ASTRA_CLIENT_SECRET = os.environ.get('ASTRA_CLIENT_SECRET', '')
# For a basic local connection:
cluster = Cluster(['127.0.0.1']) # Or specify actual contact points
session = None
try:
session = cluster.connect() # Connects to a default or specified keyspace
session.execute("""
CREATE KEYSPACE IF NOT EXISTS my_keyspace WITH replication = {
'class': 'SimpleStrategy', 'replication_factor': '1'
}
""")
session.set_keyspace('my_keyspace')
session.execute("""
CREATE TABLE IF NOT EXISTS users (
id UUID PRIMARY KEY,
name text,
age int
)
""")
print("Table 'users' created or already exists.")
session.execute(
"INSERT INTO users (id, name, age) VALUES (uuid(), %s, %s)",
("John Doe", 30)
)
print("Data inserted.")
rows = session.execute("SELECT name, age FROM users WHERE age > 25")
for row in rows:
print(f"User: {row.name}, Age: {row.age}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
if session:
session.shutdown()
if cluster:
cluster.shutdown()
Debug
Known issues
breakingMajor API changes were introduced between 2.x and 3.x series, affecting `Cluster.connect()` method signatures, result set iteration, and asynchronous APIs. Direct upgrades without code changes will likely fail.fixConsult the official 'Upgrading from Older Drivers' guide in the documentation (e.g., `docs.datastax.com/en/developer/python-driver/3.29/changelog/#upgrading-from-older-drivers`) for detailed migration steps.
affects: 2.x to 3.x
gotchaFailing to call `.shutdown()` on `Cluster` and `Session` objects can lead to resource leaks (e.g., open connections, threads) and prevent application processes from exiting cleanly, especially in long-running applications or multi-process/multi-threaded contexts.fixAlways ensure `cluster.shutdown()` and `session.shutdown()` are called in a `finally` block to guarantee resource release. The objects do not support direct `with Cluster(...) as cluster:` context management, requiring explicit shutdown.
affects: All versions
gotchaCreating new `Cluster` or `Session` objects for every database operation is a significant performance anti-pattern. These objects are designed to be long-lived, thread-safe, and shared throughout the application, managing connection pools efficiently.fixInstantiate `Cluster` and `Session` objects once per application lifecycle and reuse them. Store them in a global singleton, an application context, or pass them as dependencies.
affects: All versions
gotchaPrepared statements are cached by the driver. If the schema of a table (e.g., columns added/removed, types changed) changes after a statement has been prepared, existing prepared statements might become invalid or lead to runtime errors (e.g., `InvalidQueryError`). The driver does not automatically re-prepare statements upon schema changes.fixIf schema changes are anticipated, consider clearing the prepared statement cache (`session.clear_cache()`) or re-preparing affected statements explicitly after the schema update. Design your application to handle `InvalidQueryError` for prepared statements gracefully.
affects: All versions
breakingThe Python driver requires a running Apache Cassandra or DataStax Astra DB instance to connect. A `ConnectionRefusedError` indicates the driver was unable to establish a connection to the specified host and port (typically 127.0.0.1:9042), suggesting the database server is not running, is unreachable, or configured incorrectly.fixEnsure that the Apache Cassandra database server (or DataStax Astra DB) is running and accessible from the client machine on the specified host and port. Verify network connectivity, firewall rules, and the `listen_address`/`rpc_address` configuration in `cassandra.yaml` if running a local Cassandra instance.
affects: All versions
breakingInstallation of older `cassandra-driver` versions on Python 3.13+ fails due to outdated build scripts (e.g., `ez_setup.py`) which rely on `pkg_resources` and `tarfile.chown()` signatures that have changed or been removed in recent Python versions. This prevents the package from being built or installed.fixUse a `cassandra-driver` version that explicitly supports Python 3.13+ (check the official documentation for compatibility). Alternatively, install the driver on an older, compatible Python version (e.g., Python 3.12 or earlier) if upgrading the driver is not feasible.
affects: Older versions of `cassandra-driver` (likely 3.28.0 and below) when installed on Python 3.13 and later.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cassandra.cluster'
The cassandra-driver Python package is not installed or not accessible in the current Python environment. This often happens if the package was never installed, or if there's a Python environment mismatch.
fixEnsure the DataStax Python Driver for Apache Cassandra is installed using pip: `pip install cassandra-driver`.
NoHostAvailable
The driver failed to connect to any of the specified Cassandra contact points. This can occur if Cassandra nodes are down, IP addresses or ports are incorrect, or network/firewall issues prevent connection.
fixVerify that your Cassandra cluster nodes are running (`nodetool status`), check the accuracy of contact point IP addresses and the CQL port (default 9042), and ensure no network or firewall rules are blocking communication. Consider configuring a `ReconnectionPolicy` in your `Cluster` configuration to handle transient outages.
AuthenticationFailed
The driver failed to authenticate with the Cassandra cluster. This usually means the provided username or password is incorrect, or the Cassandra cluster's authentication settings (e.g., `authenticator` in `cassandra.yaml`) are misconfigured.
fixDouble-check the username and password used for the connection. Confirm that `authenticator: PasswordAuthenticator` (or the appropriate authenticator for your setup) is correctly configured in `cassandra.yaml` on all Cassandra nodes and that the nodes have been restarted after changes.
ReadTimeoutException
A read query did not receive enough responses from the Cassandra replicas within the configured timeout period. This can be caused by high network latency, overloaded Cassandra nodes, large data partitions requiring more time to read, or a client-side timeout that is too short.
fixIncrease the `read_timeout_millis` setting in your Cluster configuration to allow more time for responses. Investigate Cassandra node performance (CPU, memory, disk I/O), network latency between nodes, and optimize your data model to avoid excessively large partitions or rows, which can contribute to slow reads.
Upgrade
Version history
3.30.1latest on PyPI · released Jul 6, 2026
Audit
Dependencies
No dependency data recorded yet.