Dev Solve

English

中文
日本語

English

中文
日本語

Appearance

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 ​

Install these essential packages to resolve the missing dependencies:

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

After installing these packages, reattempt the installation:

bash
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:

bash
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:

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

Fedora/RHEL/CentOS:

bash
sudo dnf install gcc mysql-devel python3-devel

Dockerfile (Debian-based images):

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

macOS (Homebrew):

bash
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:

bash
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
dockerfile
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.