# Installation

## Supported Platforms

Python versions 3.10-3.14 are supported. Both CPython (the standard Python
implementation) and [PyPy](http://pypy.org) are supported and tested.

Linux, OSX, and Windows are supported.

## Installation through pip

[pip](https://pypi.org/project/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\*:

```default
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](#optional-non-python-dependencies) first. The driver may need to be reinstalled if dependencies are added after the initial installation.

## Verifying your Installation

To check if the installation was successful, you can run:

```default
python -c 'import cassandra; print(cassandra.__version__)'
```

It should print something like “3.29.11”.

## (*Optional*) Compression Support

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:

```default
pip install lz4
```

For snappy support:

```default
pip install python-snappy
```

(If using a Debian Linux derivative such as Ubuntu, it may be easier to
just run `apt-get install python-snappy`.)

### Speeding Up Installation

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](#cython-extensions).
You can also use `CASS_DRIVER_BUILD_CONCURRENCY` to increase the number of
threads used to build the driver and any C extensions:

```bash
$ CASS_DRIVER_BUILD_CONCURRENCY=8 pip install scylla-driver
```

Note that by default (when CASS_DRIVER_BUILD_CONCURRENCY is not specified), concurrency will be equal to the number of
logical cores on your machine.

### OSX Installation Error

If you’re installing on OSX and have XCode 5.1 installed, you may see an error like this:

```default
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:

```bash
ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install scylla-driver
```

<a id="windows-build"></a>

## Windows Installation Notes

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](http://aka.ms/vcpython27)
(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).

## Manual Installation

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
[pyproject.toml](https://github.com/scylladb/python-driver/blob/master/pyproject.toml).

Once the dependencies are installed, simply run:

```default
pip install .
```

## (*Optional*) Non-python Dependencies

The driver has several **optional** features that have non-Python dependencies.

### C Extensions

By default, a number of extensions are compiled, providing faster hashing
for token-aware routing with the `Murmur3Partitioner`,
[libev](http://software.schmorp.de/pkg/libev.html) event loop integration,
and Cython optimized extensions.

Extensions can be selectively disabled using environment variables:
`CASS_DRIVER_NO_EXTENSIONS=1` (disable all), `CASS_DRIVER_NO_CYTHON=1`,
or `CASS_DRIVER_NO_LIBEV=1`.

To compile the extensions, ensure that GCC and the Python headers are available.

On Ubuntu and Debian, this can be accomplished by running:

```default
$ sudo apt-get install gcc python-dev
```

On RedHat and RedHat-based systems like CentOS and Fedora:

```default
$ sudo yum install gcc python-devel
```

On OS X, homebrew installations of Python should provide the necessary headers.

See [Windows Installation Notes](#windows-build) for notes on configuring the build environment on Windows.

<a id="cython-extensions"></a>

#### Cython-based Extensions

By default, this package uses [Cython](http://cython.org/) 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 an environment variable:

```default
CASS_DRIVER_NO_CYTHON=1 pip install scylla-driver
```

Alternatively, the environment variable can be used to switch this option regardless of
context:

```default
CASS_DRIVER_NO_CYTHON=1 <your script here>
- or, to disable all extensions:
CASS_DRIVER_NO_EXTENSIONS=1 <your script here>
```

These environment variables are the preferred option, and will
prevent Cython from being materialized as a setup requirement.

If your sudo configuration does not allow SETENV, you must first install
dependencies, then install the driver:

```default
sudo pip install futures
sudo CASS_DRIVER_NO_CYTHON=1 pip install scylla-driver
```

### Supported Event Loops

For Python versions before 3.12 the driver uses the `asyncore` module for its default
event loop.  Other event loops such as `libev`, `gevent` and `eventlet` are also
available via Python modules or C extensions.  Python 3.12 has removed `asyncore` entirely
so for this platform one of these other event loops must be used.

### libev support

If you’re on Linux, you should be able to install libev
through a package manager.  For example, on Debian/Ubuntu:

```default
$ sudo apt-get install libev4 libev-dev
```

On RHEL/CentOS/Fedora:

```default
$ sudo yum install libev libev-devel
```

If you’re on Mac OS X, you should be able to install libev
through [Homebrew](http://brew.sh/). For example, on Mac OS X:

```default
$ brew install libev
```

The libev extension can now be built for Windows as of Python driver version 3.29.11.  You can
install libev using any Windows package manager.  For example, to install using [vcpkg](https://vcpkg.io):

> $ vcpkg install libev

If successful, you should be able to build and install the extension
(just using `pip install .`) and then use
the libev event loop by doing the following:

```python
>>> from cassandra.io.libevreactor import LibevConnection
>>> from cassandra.cluster import Cluster

>>> cluster = Cluster()
>>> cluster.connection_class = LibevConnection
>>> session = cluster.connect()
```

## (*Optional*) Configuring SSL

See the [Security](https://python-driver.docs.scylladb.com/stable/security.md#security) section for details on configuring SSL.