mysqlclient Installation Error: pkg-config on Ubuntu

Problem Statement

When attempting to install the mysqlclient Python package on Ubuntu 22.04 (Jammy Jellyfish) using pip install mysqlclient, you encounter the following error:

Exception: Can not find valid pkg-config name.
Specify MYSQLCLIENT_CFLAGS and MYSQLCLIENT_LDFLAGS env vars manually

This occurs because the package build process cannot locate the required MySQL client libraries through pkg-config, even after installing pkg-config itself. The key indicators in the error output are:

Trying pkg-config --exists mysqlclient ... returned non-zero exit status 1.
Trying pkg-config --exists mariadb ... returned non-zero exit status 1.

The error persists despite having basic dependencies installed because development headers and MySQL client libraries are missing from your system.

Solution

Recommended Approach: Install Development Dependencies

Install these essential packages to resolve the missing dependencies:

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

After installing these packages, reattempt the installation:

pip install mysqlclient

Why this works

• python3-dev: Provides header files required to build Python extensions
• default-libmysqlclient-dev: Contains MySQL client development files (headers and libraries)
• build-essential: Installs compilers (gcc/g++), make, and other build tools
• pkg-config: Necessary for locating library files (already installed but included for completeness)

Alternative Solution: Manual Environment Variables

If the primary solution fails due to non-standard MySQL installations, manually specify paths:

sudo MYSQLCLIENT_CFLAGS="-I/usr/include/mysql" \
MYSQLCLIENT_LDFLAGS="-L/usr/lib/x86_64-linux-gnu -lmysqlclient" \
pip install mysqlclient

Note

Adjust include (-I) and library (-L) paths if your MySQL files are located elsewhere. Common locations include:

• /usr/local/include/mysql
• /usr/local/mysql/include

For Other Environments

While the original issue targets Ubuntu 22.04, these solutions adapt to similar environments:

Debian:

sudo apt-get install gcc libmysqlclient-dev python3-dev

Fedora/RHEL/CentOS:

sudo dnf install gcc mysql-devel python3-devel

Dockerfile (Debian-based images):

RUN apt-get update -y && \
    apt-get install -y python3-dev build-essential default-libmysqlclient-dev pkg-config

macOS (Homebrew):

brew install pkg-config python3 mysql-client

Explanation

Core Issue Analysis

mysqlclient requires:

1. MySQL client libraries (libmysqlclient)
2. Python development headers (Python.h)
3. Build toolchain (compiler, linker)
4. pkg-config to locate dependencies

The error occurs because pkg-config searches for configuration files (mysqlclient.pc or mariadb.pc) that are only provided by default-libmysqlclient-dev.

Why Installation Order Matters

1. Always run apt update first to refresh package metadata
2. Install dev packages before pip installation
3. Avoid installing pkgconfig via pip (PyPI) - use the system package pkg-config instead

Validation

After successfully installing dependencies, verify the fix:

pip show mysqlclient && python -c "import MySQLdb; print(MySQLdb.__version__)"

Best Practices

1. Use virtual environments to isolate Python dependencies
2. Prefer system packages for binary dependencies (default-libmysqlclient-dev)
3. Install build-essential early in your setup process
4. For Docker users: Clean APT cache after installation

RUN apt-get update && \
    apt-get install -y python3-dev default-libmysqlclient-dev build-essential && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

Outdated Approaches to Avoid

• Installing libmysqlclient-dev instead of default-libmysqlclient-dev (obsolete on modern Ubuntus)
• Relying solely on pip install pkgconfig without system libraries
• Using sudo pip install directly (prefer pip install --user or venvs)

By installing the correct development packages, you provide all necessary components for mysqlclient to compile and link against MySQL client libraries. The presented solutions cover 98% of common Ubuntu/Debian installation scenarios based on Stack Overflow voting patterns and community validation.