Install & Compatibility
Where this runs
tested against v6.2.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
✓ 3.47s
py 3.11
✕ build_error
✓ 3.33s
py 3.12
✕ build_error
✓ 4.1s
py 3.13
✕ build_error
✓ 3.87s
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cqlsh functionality
✓ from cassandra.cluster import Cluster
✗ import cqlsh
The `cqlsh` package provides a command-line client. It is not designed for direct programmatic import as a library. For programmatic interaction with Cassandra from Python, use the `cassandra-driver` library (e.g., `from cassandra.cluster import Cluster`), which `cqlsh` itself depends on.
This quickstart demonstrates how to invoke the `cqlsh` command-line tool from Python using the `subprocess` module to execute a CQL query. It checks for the Cassandra release version. Ensure a Cassandra cluster is running and accessible (e.g., on localhost:9042) before running this code.
import subprocess
import os
# Ensure Cassandra is running, e.g., via Docker:
# docker run --name my-cassandra -p 9042:9042 -d cassandra:latest
# Execute a simple CQL command using cqlsh via subprocess
try:
# -e for executing a single command
# You can specify host/port if not localhost:9042
# e.g., ['cqlsh', 'your_host_ip', 'your_port', '-e', ...]
# If authentication is needed: ['cqlsh', '--username', 'user', '--password', 'pass', '-e', ...]
result = subprocess.run(
['cqlsh', '-e', 'SELECT release_version FROM system.local;'],
capture_output=True,
text=True,
check=True # Raise an error for non-zero exit codes
)
print("cqlsh Output (Cassandra Release Version):")
print(result.stdout.strip())
print("\nSuccessfully connected and executed query.")
except FileNotFoundError:
print("Error: 'cqlsh' command not found. Make sure cqlsh is installed and in your system PATH.")
except subprocess.CalledProcessError as e:
print(f"Error executing cqlsh: {e.returncode}")
print(f"Stderr: {e.stderr.strip()}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
cqlsh --version
Debug
Known issues
breakingcqlsh version compatibility with Cassandra server versions. Using an cqlsh version significantly different from your Cassandra cluster can lead to missing features, unexpected behavior, or connection errors due to protocol mismatches.fixAlways try to use a `cqlsh` version that is compatible with your Cassandra cluster version. Generally, `cqlsh` from the same major Cassandra distribution is recommended. For example, use cqlsh 6.x for Cassandra 4.x.
affects: < 6.0.0 (for Cassandra 4.x), general mismatch across major Cassandra versions
gotchaConnection refused or NoHostAvailable error. `cqlsh` requires a running Cassandra cluster to connect to. If the cluster is down, inaccessible, or on a different host/port, connection attempts will fail.fixEnsure your Cassandra cluster is running and listening on the expected host and port (default is localhost:9042). Verify network connectivity. Use `cqlsh <host> <port>` to specify the connection details if not default.
affects: All versions
gotchaAuthentication failures (`AuthenticationFailed`). If your Cassandra cluster is configured to require authentication, `cqlsh` will fail to connect without valid credentials.fixProvide the necessary username and password using the `--username` and `--password` command-line options, or configure them in your `cqlshrc` file.
affects: All versions
gotcha`cqlsh` is a command-line tool, not a Python library for direct import. Attempting to `import cqlsh` for programmatic interaction with Cassandra will not work as expected.fixFor programmatic interaction with Cassandra from Python, use the `cassandra-driver` library (e.g., `from cassandra.cluster import Cluster`). To execute `cqlsh` commands from Python, use `subprocess`.
affects: All versions
Errors
Common errors & fixes
Connection refused
The Cassandra cluster is not running or is not accessible on the specified host/port.
fixStart your Cassandra cluster. Verify Cassandra's listening address and port (e.g., `netstat -tulnp | grep 9042` on Linux). Use `cqlsh <host> <port>` if Cassandra is not on the default `localhost:9042`.
cqlsh: command not found
The `cqlsh` executable is not in your system's PATH environment variable.
fixEnsure `cqlsh` is installed (`pip install cqlsh`). Locate the installation directory for Python scripts (e.g., `~/.local/bin` or `C:\Python\Scripts`) and add it to your system's PATH. Restart your terminal.
AuthenticationFailed: Failed to authenticate to <ip-address>:9042
The Cassandra cluster requires authentication, but `cqlsh` was run without correct credentials, or with no credentials.
fixProvide a valid username and password using `cqlsh --username <user> --password <pass>` or configure credentials in your `~/.cqlshrc` file.
ServerError: code=2000 [Syntax error in CQL query] message="line 1:XX no viable alternative at input '...'"
The CQL statement provided to `cqlsh` has a syntax error.
fixCarefully review the CQL query for typos, missing keywords, incorrect punctuation, or features not supported by your specific Cassandra version. Consult the Apache Cassandra CQL documentation.
Upgrade
Version history
6.2.2latest on PyPI · released Apr 16, 2026
Audit
Dependencies
cassandra-driverrequiredcqlsh uses the official DataStax Python Driver for Apache Cassandra internally to connect and interact with Cassandra clusters.
geometoptionalUsed for handling geographic data types within CQL, particularly for geospatial functions.