Practice Now
MySQL
MySQLdb
Python
Installation Error
Troubleshooting

mysql_config not found when installing mysqldb python interface

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design
DatabasesPythonDebugging & Errors

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
Related reading
Course
Beginner
27 lessons
10 hours
System Design Fundamentals

Build a strong foundation in designing scalable, reliable distributed systems.

View the course
Track what you have practised

A free account saves your progress, solutions and study plan across every problem on Codemia.

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design
Codemia
© 2026 Codemia
Resources
Legal
Social
All Rights Reserved.