mysql_config not found when installing mysqldb python interface

MySQL

MySQLdb

Python

Installation Error

Troubleshooting

mysql_config not found when installing mysqldb python interface

Master System Design with Codemia

Enhance your system design skills with over 120 practice problems, detailed solutions, and hands-on exercises.

Start Practicing Learn More

Introduction

The mysql_config not found error occurs when installing mysqlclient (or the older MySQL-python) because the package needs the MySQL C client development headers to compile. The mysql_config binary tells pip where to find these headers and libraries. It is missing because the MySQL development package is not installed on your system. The fix is to install the appropriate -dev or -devel system package for your OS, or switch to a pure-Python MySQL driver like PyMySQL that requires no compilation.

The Error

bash

1pip install mysqlclient
2# ...
3# OSError: mysql_config not found
4# or
5# sh: mysql_config: command not found
6# or
7# EnvironmentError: mysql_config not found

This happens during the build step because mysqlclient is a C extension that wraps the MySQL C client library (libmysqlclient). The build script calls mysql_config to determine compiler flags, include paths, and library paths.

Fix by OS

Ubuntu / Debian

bash

1# Install MySQL development headers
2sudo apt-get update
3sudo apt-get install python3-dev default-libmysqlclient-dev build-essential
4
5# For specific MySQL versions
6sudo apt-get install libmysqlclient-dev    # MySQL 5.x/8.x
7
8# Now install mysqlclient
9pip install mysqlclient

The default-libmysqlclient-dev package provides mysql_config along with the headers and libraries.

Fedora

bash

sudo dnf install python3-devel mysql-devel
pip install mysqlclient

CentOS / RHEL

bash

1sudo yum install python3-devel mysql-devel
2# or for MariaDB
3sudo yum install python3-devel mariadb-devel
4
5pip install mysqlclient

macOS (Homebrew)

bash

brew install mysql pkg-config
pip install mysqlclient

If mysql_config is still not found after installing:

bash

1# Find where mysql_config is
2brew --prefix mysql
3# /opt/homebrew/opt/mysql (Apple Silicon)
4# /usr/local/opt/mysql (Intel)
5
6# Add to PATH
7export PATH="/opt/homebrew/opt/mysql/bin:$PATH"
8
9# Or set the config path for pip
10export MYSQLCLIENT_CFLAGS=$(mysql_config --cflags)
11export MYSQLCLIENT_LDFLAGS=$(mysql_config --libs)
12pip install mysqlclient

macOS (mysql-client only, no server)

bash

1brew install mysql-client pkg-config
2echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc
3source ~/.zshrc
4pip install mysqlclient

Alpine Linux (Docker)

dockerfile

RUN apk add --no-cache mariadb-dev gcc musl-dev python3-dev
RUN pip install mysqlclient

Alternative: Use PyMySQL (No Compilation)

PyMySQL is a pure-Python MySQL driver that does not need mysql_config or any C libraries:

bash

pip install PyMySQL

python

1import pymysql
2
3connection = pymysql.connect(
4    host='localhost',
5    user='root',
6    password='password',
7    database='mydb'
8)
9
10with connection.cursor() as cursor:
11    cursor.execute("SELECT * FROM users")
12    rows = cursor.fetchall()

Using PyMySQL as a MySQLdb Drop-In

python

1# Add this at the top of your application (before any MySQLdb import)
2import pymysql
3pymysql.install_as_MySQLdb()
4
5# Now MySQLdb imports use PyMySQL internally
6import MySQLdb  # Actually uses PyMySQL

This is useful for Django and other frameworks that expect MySQLdb.

Alternative: mysql-connector-python

Oracle's official pure-Python driver:

bash

pip install mysql-connector-python

python

1import mysql.connector
2
3connection = mysql.connector.connect(
4    host='localhost',
5    user='root',
6    password='password',
7    database='mydb'
8)
9cursor = connection.cursor()
10cursor.execute("SELECT * FROM users")

Verifying mysql_config

bash

1# Check if mysql_config exists
2which mysql_config
3# /usr/bin/mysql_config
4
5# See what it outputs
6mysql_config --cflags
7# -I/usr/include/mysql
8
9mysql_config --libs
10# -L/usr/lib/x86_64-linux-gnu -lmysqlclient -lpthread -ldl -lssl -lcrypto
11
12mysql_config --version
13# 8.0.36

Docker Setup

dockerfile

1FROM python:3.11-slim
2
3# Install system dependencies
4RUN apt-get update && \
5    apt-get install -y default-libmysqlclient-dev build-essential pkg-config && \
6    rm -rf /var/lib/apt/lists/*
7
8# Install Python package
9RUN pip install mysqlclient
10
11COPY . /app
12WORKDIR /app
13CMD ["python", "app.py"]

Django Configuration

python

1# settings.py: using mysqlclient (requires mysql_config)
2DATABASES = {
3    'default': {
4        'ENGINE': 'django.db.backends.mysql',
5        'NAME': 'mydb',
6        'USER': 'root',
7        'PASSWORD': 'password',
8        'HOST': 'localhost',
9        'PORT': '3306',
10    }
11}
12
13# Or with PyMySQL (no mysql_config needed)
14# In manage.py or wsgi.py:
15import pymysql
16pymysql.install_as_MySQLdb()

Common Pitfalls

Installing mysql-server instead of *-dev: The MySQL server package does not include development headers. You specifically need libmysqlclient-dev (Debian) or mysql-devel (RHEL/Fedora).
MariaDB vs MySQL headers: On many Linux distributions, MariaDB replaces MySQL. The mariadb-devel or libmariadb-dev package provides a compatible mysql_config. Check which is available with your package manager.
Virtual environment PATH: mysql_config must be on the system PATH, not in the virtualenv. If which mysql_config returns nothing, the dev package is not installed or the path is not set.
macOS Apple Silicon paths: Homebrew installs to /opt/homebrew/ on Apple Silicon instead of /usr/local/. Many guides show the Intel path. Use brew --prefix mysql to find the correct location.
Using MySQL-python on Python 3: The MySQL-python package (also called MySQLdb) only supports Python 2. Use mysqlclient (its maintained fork) for Python 3.

Summary

mysql_config not found means the MySQL C client development headers are missing
Install default-libmysqlclient-dev (Debian/Ubuntu), mysql-devel (Fedora/CentOS), or brew install mysql (macOS)
For a compilation-free alternative, use PyMySQL with pymysql.install_as_MySQLdb() for framework compatibility
In Docker, add the dev package in your Dockerfile before pip install mysqlclient
Use which mysql_config to verify the binary is available on your PATH