You're viewing documentation for a previous version of Scylla Python Driver. Switch to the latest stable version.
Python 2.7, 3.4, 3.5, 3.6, 3.7 and 3.8 are supported. Both CPython (the standard Python implementation) and PyPy are supported and tested.
Linux, OSX, and Windows are supported.
pip is the suggested tool for installing packages. It will handle installing all Python dependencies for the driver at the same time as the driver itself. To install the driver*:
pip install scylla-driver
You can use
pip install --pre scylla-driver if you need to install a beta version.
*Note: if intending to use optional extensions, install the dependencies first. The driver may need to be reinstalled if dependencies are added after the initial installation.
To check if the installation was successful, you can run:
python -c 'import cassandra; print cassandra.__version__'
It should print something like “3.21.0”.
The driver provides an optional fluent graph API that depends on Apache TinkerPop (gremlinpython). It is not installed by default. To be able to build Gremlin traversals, you need to install the graph requirements:
pip install scylla-driver[graph]
See graph_fluent for more details about this API.
Compression can optionally be used for communication between the driver and Cassandra. There are currently two supported compression algorithms: snappy (in Cassandra 1.2+) and LZ4 (only in Cassandra 2.0+). If either is available for the driver and Cassandra also supports it, it will be used automatically.
For lz4 support:
pip install lz4
For snappy support:
pip install python-snappy
(If using a Debian Linux derivative such as Ubuntu, it may be easier to
apt-get install python-snappy.)
The driver has built-in support for capturing
the queries you run. However, the
scales library is required to
pip install scales
By default, installing the driver through
pip uses a pre-compiled, platform-specific wheel when available.
If using a source distribution rather than a wheel, Cython is used to compile certain parts of the driver.
This makes those hot paths faster at runtime, but the Cython compilation
process can take a long time – as long as 10 minutes in some environments.
In environments where performance is less important, it may be worth it to
disable Cython as documented below.
You can also use
CASS_DRIVER_BUILD_CONCURRENCY to increase the number of
threads used to build the driver and any C extensions:
$ # installing from source $ CASS_DRIVER_BUILD_CONCURRENCY=8 python setup.py install $ # installing from pip $ CASS_DRIVER_BUILD_CONCURRENCY=8 pip install scylla-driver
If you’re installing on OSX and have XCode 5.1 installed, you may see an error like this:
clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]
To fix this, re-run the installation with an extra compilation flag:
ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install scylla-driver
Installing the driver with extensions in Windows sometimes presents some challenges. A few notes about common hang-ups:
Setup requires a compiler. When using Python 2, this is as simple as installing this package (this link is also emitted during install if setuptools is unable to find the resources it needs). Depending on your system settings, this package may install as a user-specific application. Make sure to install for everyone, or at least as the user that will be building the Python environment.
It is also possible to run the build with your compiler of choice. Just make sure to have your environment setup with the proper paths. Make sure the compiler target architecture matches the bitness of your Python runtime. Perhaps the easiest way to do this is to run the build/install from a Visual Studio Command Prompt (a shortcut installed with Visual Studio that sources the appropriate environment and presents a shell).
You can always install the driver directly from a source checkout or tarball. When installing manually, ensure the python dependencies are already installed. You can find the list of dependencies in requirements.txt.
Once the dependencies are installed, simply run:
python setup.py install
The driver has several optional features that have non-Python dependencies.
By default, a number of extensions are compiled, providing faster hashing
for token-aware routing with the
libev event loop integration,
and Cython optimized extensions.
When installing manually through setup.py, you can disable both with
--no-extensions option, or selectively disable them with
To compile the extensions, ensure that GCC and the Python headers are available.
On Ubuntu and Debian, this can be accomplished by running:
$ sudo apt-get install gcc python-dev
On RedHat and RedHat-based systems like CentOS and Fedora:
$ sudo yum install gcc python-devel
On OS X, homebrew installations of Python should provide the necessary headers.
See Windows Installation Notes for notes on configuring the build environment on Windows.
By default, this package uses Cython to optimize core modules and build custom extensions. This is not a hard requirement, but is engaged by default to build extensions offering better performance than the pure Python implementation.
This is a costly build phase, especially in clean environments where the Cython compiler must be built This build phase can be avoided using the build switch, or an environment variable:
python setup.py install --no-cython
Alternatively, an environment variable can be used to switch this option regardless of context:
CASS_DRIVER_NO_CYTHON=1 <your script here> - or, to disable all extensions: CASS_DRIVER_NO_EXTENSIONS=1 <your script here>
This method is required when using pip, which provides no other way of injecting user options in a single command:
CASS_DRIVER_NO_CYTHON=1 pip install scylla-driver CASS_DRIVER_NO_CYTHON=1 sudo -E pip install ~/python-driver
The environment variable is the preferred option because it spans all invocations of setup.py, and will prevent Cython from being materialized as a setup requirement.
If your sudo configuration does not allow SETENV, you must push the option flag down via pip. However, pip applies these options to all dependencies (which break on the custom flag). Therefore, you must first install dependencies, then use install-option:
sudo pip install six futures sudo pip install --install-option="--no-cython"
The driver currently uses Python’s
asyncore module for its default
event loop. For better performance,
libev is also supported through
a C extension.
If you’re on Linux, you should be able to install libev through a package manager. For example, on Debian/Ubuntu:
$ sudo apt-get install libev4 libev-dev
$ sudo yum install libev libev-devel
If you’re on Mac OS X, you should be able to install libev through Homebrew. For example, on Mac OS X:
$ brew install libev
The libev extension is not built for Windows (the build process is complex, and the Windows implementation uses select anyway).
If successful, you should be able to build and install the extension
setup.py build or
setup.py install) and then use
the libev event loop by doing the following:
>>> from cassandra.io.libevreactor import LibevConnection >>> from cassandra.cluster import Cluster >>> cluster = Cluster() >>> cluster.connection_class = LibevConnection >>> session = cluster.connect()
Andrew Mussey has published a thorough guide on Using SSL with the DataStax Python driver.
cassandra- Exceptions and Enums
cassandra.cluster- Clusters and Sessions
cassandra.policies- Load balancing and Failure Handling Policies
cassandra.graph- Graph Statements, Options, and Row Factories
cassandra.metadata- Schema and Ring Topology
cassandra.metrics- Performance Metrics
cassandra.query- Prepared Statements, Batch Statements, Tracing, and Row Factories
cassandra.pool- Hosts and Connection Pools
cassandra.protocol- Protocol Features
cassandra.encoder- Encoders for non-prepared Statements
cassandra.decoder- Data Return Formats
cassandra.concurrent- Utilities for Concurrent Statement Execution
cassandra.connection- Low Level Connection Info
cassandra.timestamps- Timestamp Generation
gevent-compatible Event Loop
cassandra.io.twistedreactor- Twisted Event Loop
cassandra.cqlengine.models- Table models for object mapping
cassandra.cqlengine.columns- Column types for object mapping models
cassandra.cqlengine.query- Query and filter model objects
cassandra.cqlengine.connection- Connection management for cqlengine
cassandra.cqlengine.management- Schema management for cqlengine
cassandra.cqlengine.usertype- Model classes for User Defined Types
cassandra.datastax.graph- Graph Statements, Options, and Row Factories
On this page