Install mysqlclient in Python

mysqlclient is a fast and mature MySQL connector for Python. It is the recommended driver for Django projects that use MySQL.

This guide covers installation on Linux, macOS, and Windows. It also explains the most common errors and how to fix them cleanly.

Every section includes working code and clear explanations. Beginners can follow each step without guesswork.

What Is mysqlclient

mysqlclient is a fork of MySQLdb1. It adds Python 3 support and fixes many long-standing bugs.

It is not a pure Python library. The package includes C extensions that talk directly to the MySQL client library.

This design makes it fast. It also means you need MySQL development headers on your system before installation.

Most Django projects use it as the default MySQL backend. If you plan to connect Django to MySQL, this is the right choice.

Prerequisites

You need Python 3.7 or newer and a working MySQL or MariaDB server. You also need build tools and development headers.

The headers provide the mysql_config utility. The installer uses it to find compiler and linker flags.

Without the headers, installation fails with OSError: mysql_config not found.

Start by creating a virtual environment. This keeps the package isolated from your system Python.

# Create a virtual environment
python -m venv mysql-env

# Activate on Linux or macOS
source mysql-env/bin/activate

# Activate on Windows
mysql-env\Scripts\activate

Your prompt should change after activation. Confirm the interpreter path with which python or where python.

Install on Debian or Ubuntu

Install the development headers first. Then install the Python package with pip.

The headers package on modern Debian and Ubuntu is default-libmysqlclient-dev. It replaces the older libmysqlclient-dev package.

sudo apt-get update
sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config

After the headers are in place, install mysqlclient with pip.

pip install mysqlclient

You can confirm the build flags with pkg-config if the installation reports missing libraries.

pkg-config --cflags --libs mysqlclient

This command prints the include and linker flags. If it returns an error, the development headers are not installed correctly.

Install on Red Hat or CentOS

On Red Hat based systems, the package names differ. Install the Python development headers and the MySQL development library.

sudo yum install python3-devel mysql-devel pkgconfig

Then install the package with pip.

pip install mysqlclient

On newer Fedora or CentOS Stream systems, use dnf instead of yum. The package names are the same.

sudo dnf install python3-devel mysql-devel pkgconfig

Install on macOS with Homebrew

macOS requires Homebrew packages for MySQL and pkg-config. Install both before running pip.

brew install mysql pkg-config
pip install mysqlclient

If you do not need a full MySQL server, install mysql-client instead. You must also set PKG_CONFIG_PATH so the installer finds the client library.

brew install mysql-client pkg-config
export PKG_CONFIG_PATH="$(brew --prefix)/opt/mysql-client/lib/pkgconfig"
pip install mysqlclient

The environment variable is temporary. Add it to your shell profile if you install this package often.

Install on Windows

Windows is the hardest platform for this package. The official documentation says building from source is very difficult.

Fortunately, prebuilt binary wheels exist for most Python versions. Try pip first.

pip install mysqlclient

If pip cannot find a wheel, you need the MariaDB C Connector. Download and install it from the MariaDB website.

Use the default installation path: C:\Program Files\MariaDB\MariaDB Connector C. The installer looks there automatically.

If you install the connector elsewhere, set the MYSQLCLIENT_CONNECTOR environment variable before running pip.

set MYSQLCLIENT_CONNECTOR="C:\custom\path\MariaDB Connector C"
pip install mysqlclient

You also need the correct Visual Studio build tools for your Python version. The wheel usually avoids this requirement.

Fix mysql_config Not Found

This is the most common installation error. It means the installer cannot locate the MySQL client configuration tool.

The fix depends on your operating system. On Debian or Ubuntu, install the development headers.

sudo apt-get install default-libmysqlclient-dev

On Red Hat or CentOS, install the MySQL development package.

sudo yum install mysql-devel

On macOS, install MySQL or mysql-client through Homebrew. Then set PKG_CONFIG_PATH if needed.

On Windows, install the MariaDB C Connector. Make sure it is in the default location.

If mysql_config exists but is not found, add its directory to your PATH.

export PATH="$PATH:/usr/local/mysql/bin"

After fixing the path, run pip install mysqlclient again.

Use mysqlclient with Django

After installation, configure Django to use MySQL. Open your settings.py file and update the DATABASES setting.

Use django.db.backends.mysql as the engine. Provide the database name, user, password, host, and port.

# settings.py
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "NAME": "mydatabase",
        "USER": "mydatabaseuser",
        "PASSWORD": "mypassword",
        "HOST": "127.0.0.1",
        "PORT": "3306",
    }

If your Django views filter database records heavily, keep the query logic clean with django-filter in Python. Clean filters reduce unexpected errors in production.

Run python manage.py migrate to confirm the connection works. Django uses mysqlclient for every database operation.

Troubleshoot Other Common Errors

Some errors appear after installation succeeds. These are usually environment or version issues.

ModuleNotFoundError: No module named 'MySQLdb'

This error means mysqlclient is not installed in the active environment. Activate your virtual environment and install it again.

Check the interpreter path with which python or where python. A mismatched path is the usual cause.

Error Loading MySQLdb Module

Django raises this error when it cannot load the MySQL backend. Confirm that mysqlclient is installed in the same environment as Django.

If both are installed, check for conflicting packages like mysql-connector-python. Remove or isolate them.

Compilation Errors on Linux

Missing pkg-config or build tools cause compilation failures. Install build-essential and pkg-config along with the headers.

sudo apt-get install build-essential pkg-config

Then retry the installation. The installer uses pkg-config to locate the client library.

Best Practices for a Clean Setup

Pin the package version in your requirements.txt. This keeps builds reproducible across environments.

pip freeze | grep mysqlclient >> requirements.txt

Never hardcode database credentials in settings.py. Read them from environment variables.

import os

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "NAME": os.environ["DB_NAME"],
        "USER": os.environ["DB_USER"],
        "PASSWORD": os.environ["DB_PASSWORD"],
        "HOST": os.environ.get("DB_HOST", "127.0.0.1"),
        "PORT": os.environ.get("DB_PORT", "3306"),
    }

Use the same package version across development, staging, and production. Version drift causes subtle query behavior changes.

Monitor database errors in production. You can install sentry-sdk in Python to capture connection failures and slow queries automatically.

If your application also stores files in the cloud, consider how you will upload files to GCS with Python alongside your MySQL setup. A clean storage layer keeps your backend simple.

Test the connection after every deployment. A quick SELECT 1 query catches credential and network issues early.

Conclusion

Installing mysqlclient in Python is a short process once the system dependencies are in place. Install the development headers for your operating system first.

On Linux, install the default-libmysqlclient-dev package. On macOS, use Homebrew. On Windows, rely on binary wheels or the MariaDB C Connector.

Fix mysql_config not found by installing the headers or setting the correct path. Then install the package with pip.

Configure Django to use the MySQL backend and verify the connection with a migration. With these steps, your Python application can talk to MySQL reliably and efficiently.