> For the complete documentation index, see [llms.txt](https://mariadb.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mariadb.com/docs/connectors/mariadb-connector-python/install.md).

# Installation

## API Reference

* [**Connection API**](/docs/connectors/mariadb-connector-python/api/connection.md) - Connection parameters, methods, and attributes
* [**Cursor API**](/docs/connectors/mariadb-connector-python/api/cursor.md) - Cursor parameters, methods, and attributes
* [**Connection Pooling API**](/docs/connectors/mariadb-connector-python/pooling.md) - Pool configuration and usage

## Prerequisites

MariaDB Connector/Python 2.0 supports

* Python 3.10 and later
* MariaDB server versions from version 10.3 or MySQL server versions from version 5.7.
* MariaDB client library (MariaDB Connector/C) from version 3.3.1 (optional - only required for C extension).

## Installation Options

{% hint style="info" %}
**Version 2.0 is currently a Release Candidate (RC); version 1.1 is the latest stable (GA) release.**

Because 2.0 is not yet GA, a plain `pip install mariadb` installs the latest stable release (1.1). To install the 2.0 release candidate you must pass the `--pre` flag, for example `pip install --pre mariadb`. Do not use non-stable (non-GA) releases in production.
{% endhint %}

### Installing Version 1.1 (Stable / GA)

Version 1.1 is the current GA release. A plain `pip install` installs the latest stable version:

```console
pip install mariadb
```

To pin to a specific 1.1 release:

```console
pip install mariadb==1.1.14
```

Version 1.1:

* Always installs the C extension
* Requires MariaDB Connector/C to be pre-installed
* Does not support pure Python or binary wheels
* Connection pooling is included by default

For version 1.1 documentation, see the [1.1 branch documentation](https://mariadb-corporation.github.io/mariadb-connector-python/).

### Installing Version 2.0 (Release Candidate)

{% hint style="info" %}
Version 2.0 is a Release Candidate. The `--pre` flag is required so that pip will select the pre-release; without it, pip installs the latest GA release (1.1).
{% endhint %}

MariaDB Connector/Python 2.0 offers three installation options:

### 1. Pure Python (Default)

Works everywhere, no compiler or C dependencies required:

```console
pip install --pre mariadb
```

This is the default installation method for 2.0. The pure Python implementation:

* Works on all Python interpreters (CPython, PyPy, etc.)
* Requires no compilation or system dependencies
* Provides good performance for most use cases
* Fully compatible with the C extension API

### 2. C Extension (Maximum Performance)

For maximum performance, install the C extension:

```console
pip install --pre mariadb[c]
```

The C extension:

* Delivers 2-12× better performance on data-heavy workloads
* **Requires MariaDB Connector/C to be pre-installed** on your system
* Requires a C compiler for building from source
* Provides the same API as the pure Python implementation

### 3. Pre-compiled Binary Wheels

Pre-compiled wheels with no local C connector required:

```console
pip install --pre mariadb[binary]
```

Binary wheels:

* Include the C extension pre-compiled
* **MariaDB Connector/C is bundled** - no separate installation needed
* No compiler required
* Available for common platforms (Windows, Linux, macOS)

### 4. With Connection Pooling

Connection pooling is now a separate optional package:

```console
pip install --pre mariadb[pool]
```

Or combine with binary wheels:

```console
pip install --pre mariadb[binary,pool]
```

### Microsoft Windows

**Option 1: Binary wheels (recommended)**

```console
pip install --pre mariadb[binary,pool]
```

**Option 2: Pure Python**

```console
pip install --pre mariadb[pool]
```

**Option 3: C extension from source**

First install MariaDB Connector/C. MSI installers for both 32-bit and 64-bit operating systems are available from [MariaDB Connector Download page](https://mariadb.com/downloads/connectors/).

Then install the C extension:

```console
pip install --pre mariadb[c,pool]
```

On success, you should see a message at the end "Successfully installed mariadb-2.0.0rc2".

```console
Collecting mariadb
Downloading mariadb-2.0.0rc2-cp311-cp311-win_amd64.whl (210 kB)
---------------------------------------- 210.0/210.0 kB 3.2 MB/s eta 0:00:00
Installing collected packages: mariadb
Successfully installed mariadb-2.0.0rc2
```

## Installation from Source

### Pure Python Installation

The pure Python implementation has minimal requirements:

```console
cd source_package_dir
pip install .
```

No compiler or system dependencies required.

### C Extension Build Prerequisites

To build the C extension from source, you will need:

* C compiler (gcc, clang, or MSVC)
* Python development files (Usually installed with package **python3-dev**). Minimum supported version is Python 3.10 (version 1.1 requires Python 3.8).
* MariaDB Connector/C libraries and header files (version 3.3.1 or later)
  * Either from MariaDB server package or from MariaDB Connector/C package
  * If your distribution doesn't provide a recent version, download from [MariaDB Connector Download page](https://mariadb.com/downloads/connectors/) or build from source
* The mariadb\_config program from MariaDB Connector/C (must be in your PATH)
* For POSIX systems: TLS libraries (GnuTLS or OpenSSL)
* Python's "packaging" module

**On POSIX systems**, ensure the PATH environment variable contains the directory with the mariadb\_config utility.

**Installing the C extension from source:**

```console
cd source_package_dir
pip install mariadb-c/
```

**Installing with pooling support:**

```console
cd source_package_dir
pip install mariadb-pool/
```

For troubleshooting, check the [Installation FAQ](/docs/connectors/mariadb-connector-python/faq.md#installation-faq).

## Test suite

If you have installed the sources, after successful build you can run the test suite from the source directory.

```console
pytest tests/ -v
```

You can configure the connection parameters by using the following environment variables

* TEST\_DB\_USER (default root)
* TEST\_DB\_PASSWORD
* TEST\_DB\_DATABASE (default ‘testp’)
* TEST\_DB\_HOST (default ‘localhost’)
* TEST\_DB\_PORT (default 3306)

{% @marketo/form formId="4316" %}