Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

pip install mysqlclient fails to build on Windows, Linux or macOS

Errorfatal error C1083: Cannot open include file: 'mysql.h': No such file or directory

Short answer

mysqlclient is a C extension. When no ready wheel matches your Python, pip builds it and needs the MySQL client headers. Install them first: the MariaDB C Connector on Windows, default-libmysqlclient-dev and pkg-config on Debian or Ubuntu, or mysql-client with pkg-config through Homebrew on macOS.

  • Applies to mysqlclient 2.2, Python 3.12, Ubuntu 24.04, macOS with Homebrew, Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the lines above the final error in the pip output. The missing file or tool named there picks the cause. Reinstall verbosely to see them.

    pip install mysqlclient -v
  2. 2Match what you see, then jump to its fix

    1. 1C1083 ... mysql.h on WindowsWindows: no wheel for your Python and no MariaDB C ConnectorFix
    2. 2metadata-generation-failed, with mysql_config or pkg-config not found, on Debian or UbuntuLinux: development headers or pkg-config are missingFix
    3. 3Build errors about missing mysql headers or libraries on macOSmacOS: Homebrew client library not on pkg-config's pathFix

What does the error look like?

  • fatal error C1083: Cannot open include file: 'mysql.h': No such file or directory
  • error: metadata-generation-failed

Cause 1 of 3

Windows: no wheel for your Python and no MariaDB C Connector

1Check

The project documents Windows wheels. If none exists for your Python version, pip builds from source, which needs the MariaDB C Connector and a matching Visual Studio.

python --version

2Fix

Install the MariaDB C Connector in its default location (C:\Program Files\MariaDB\MariaDB Connector C). If you installed it elsewhere, set MYSQLCLIENT_CONNECTOR first.

set MYSQLCLIENT_CONNECTOR=C:\Program Files\MariaDB\MariaDB Connector C
pip install mysqlclient

3Verify

The import works.

python -c "import MySQLdb; print(MySQLdb.version_info)"

Confirmed by github.com

Did this fix it?

Cause 2 of 3

Linux: development headers or pkg-config are missing

1Check

The build uses pkg-config to find the compiler and linker flags for the MySQL client library.

pkg-config --cflags --libs mysqlclient

2Fix

Install the Python and MySQL development packages, then retry.

sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config
pip install mysqlclient

3Verify

pkg-config answers and the install succeeds.

pkg-config --libs mysqlclient
python -c "import MySQLdb"

Confirmed by github.com

Did this fix it?

Cause 3 of 3

macOS: Homebrew client library not on pkg-config's path

1Check

Install a client library with Homebrew; the keg-only mysql-client is found only if PKG_CONFIG_PATH points at it.

brew list | grep -i mysql

2Fix

Install mysql-client and pkg-config, export the path, then install the package.

brew install mysql-client pkg-config
export PKG_CONFIG_PATH="$(brew --prefix)/opt/mysql-client/lib/pkgconfig"
pip install mysqlclient

3Verify

The import prints version info.

python -c "import MySQLdb; print(MySQLdb.version_info)"

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Pin mysqlclient and the Python version together in your lockfile so wheels keep matching.
  • Put the apt or brew install lines into your Dockerfile or setup script.
  • Consider a pure-Python driver if you cannot install system libraries.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.