How to Resolve "EnvironmentError: mysql_config not found" in Python

If you've ever tried installing a MySQL-related Python package like mysqlclient or MySQL-python, chances are you've run into the frustrating "EnvironmentError: mysql_config not found" message. This error occurs when Python cannot locate the mysql_config utility, a small but critical program that provides compiler and linker flags needed to build MySQL client libraries from source.

In this guide, you'll learn exactly why this error happens, how to diagnose the root cause, and how to fix it on Linux (Debian/Ubuntu, RHEL/CentOS) and macOS.

Understanding the Error

When you run a command like pip install mysqlclient, the installation process needs to compile C extensions that interface with MySQL. To do this, it calls the mysql_config (or mariadb_config) binary to discover include paths, library paths, and compiler flags. If this binary is missing or not on your system's PATH, you'll see:

EnvironmentError: mysql_config not found

or in newer versions:

OSError: mysql_config not found

info

This error does not typically occur when installing pure-Python packages like mysql-connector-python, because they don't need to compile C extensions. It specifically affects packages like mysqlclient and the legacy MySQL-python.

Common Causes

There are two primary reasons you encounter this error:

1. MySQL development libraries are not installed: The mysql_config utility ships with the MySQL (or MariaDB) development package, not with the server or client alone.
2. mysql_config is not on your PATH: The binary exists on your system but the directory containing it is not included in your PATH environment variable.

Diagnosing the Problem

Before jumping into fixes, confirm whether mysql_config is present and accessible.

Check if mysql_config exists

which mysql_config

If the command returns nothing, the utility is either not installed or not on your PATH.

Search for it manually

find / -name "mysql_config" 2>/dev/null

If this finds a path like /usr/local/mysql/bin/mysql_config, the binary exists but isn't in your PATH.

Check your current PATH

echo $PATH

Verify that the directory containing mysql_config is listed. If it's not, you'll need to add it (covered below).

How to Fix the Error

Fix 1: Install MySQL Development Libraries

This is the most common fix. You need to install the development headers and libraries for MySQL or MariaDB.

On Debian / Ubuntu:

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

On RHEL / CentOS / Fedora:

sudo yum install mysql-devel
# or for MariaDB:
sudo yum install mariadb-devel

On macOS (using Homebrew):

brew install mysql pkg-config

After installing, verify that mysql_config is now available:

which mysql_config

Expected output (example):

/usr/bin/mysql_config

Now retry the pip install:

pip install mysqlclient

tip

On some systems, the binary may be named mariadb_config instead of mysql_config. If that's the case, you can create a symlink:

sudo ln -s /usr/bin/mariadb_config /usr/bin/mysql_config

Fix 2: Add mysql_config to Your PATH

If mysql_config is installed but not on your PATH, add its directory:

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

To make this change permanent, add the line to your shell configuration file (~/.bashrc, ~/.zshrc, or ~/.bash_profile):

echo 'export PATH="/usr/local/mysql/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Then retry:

pip install mysqlclient

Fix 3: Use a Pure-Python MySQL Driver Instead

If you don't strictly need mysqlclient and want to avoid C compilation entirely, consider using mysql-connector-python (Oracle's official pure-Python driver) or PyMySQL:

pip install mysql-connector-python

or

pip install PyMySQL

These packages don't require mysql_config because they are written entirely in Python.

Here's a quick example using mysql-connector-python:

import mysql.connector

try:
    connection = mysql.connector.connect(
        user="your_username",
        password="your_password",
        host="127.0.0.1",
        database="your_database"
    )
    print("Connection successful!")
    cursor = connection.cursor()
    cursor.execute("SELECT VERSION()")
    version = cursor.fetchone()
    print(f"MySQL version: {version[0]}")
except mysql.connector.Error as err:
    print(f"Error: {err}")
finally:
    if "connection" in locals() and connection.is_connected():
        cursor.close()
        connection.close()
        print("Connection closed.")

Output:

Connection successful!
MySQL version: 8.0.36
Connection closed.

warning

If you're using a framework like Django, be aware that the default MySQL backend (django.db.backends.mysql) expects mysqlclient. If you want to use PyMySQL instead, you need to add the following to your project's __init__.py or manage.py:

import pymysql
pymysql.install_as_MySQLdb()

Using Virtual Environments (Best Practice)

Regardless of which fix you choose, always use a virtual environment to isolate your project dependencies:

python -m venv myenv
source myenv/bin/activate   # On Windows: myenv\Scripts\activate
pip install mysqlclient     # or mysql-connector-python

This prevents system-wide package conflicts and makes your project reproducible.

Quick Reference: Fix by Operating System

Operating System	Install Command
Ubuntu / Debian	sudo apt-get install default-libmysqlclient-dev build-essential pkg-config
RHEL / CentOS	sudo yum install mysql-devel
Fedora	sudo dnf install mysql-devel
macOS (Homebrew)	brew install mysql pkg-config
Any (avoid C build)	pip install mysql-connector-python or pip install PyMySQL

Conclusion

The "EnvironmentError: mysql_config not found" error in Python boils down to a missing or inaccessible MySQL development package.

In most cases, installing the appropriate development libraries for your operating system resolves the issue immediately. If compiling C extensions isn't a requirement for your project, switching to a pure-Python MySQL driver like mysql-connector-python or PyMySQL is the simplest and most portable solution.

By understanding the underlying cause, i.e. the need for mysql_config during C extension compilation, you can quickly diagnose and fix this error on any platform.