pip install mysqlclient fails to build on Windows, Linux or macOS
fatal error C1083: Cannot open include file: 'mysql.h': No such file or directoryShort 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.
Fix it fast
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 -v2Match what you see, then jump to its fix
- 1
C1083 ... mysql.h on WindowsWindows: no wheel for your Python and no MariaDB C ConnectorFix - 2
metadata-generation-failed, with mysql_config or pkg-config not found, on Debian or UbuntuLinux: development headers or pkg-config are missingFix - 3
Build errors about missing mysql headers or libraries on macOSmacOS: Homebrew client library not on pkg-config's pathFix
- 1
What does the error look like?
fatal error C1083: Cannot open include file: 'mysql.h': No such file or directoryerror: 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 --version2Fix
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 mysqlclient3Verify
The import works.
python -c "import MySQLdb; print(MySQLdb.version_info)"Confirmed by github.com
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 mysqlclient2Fix
Install the Python and MySQL development packages, then retry.
sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config
pip install mysqlclient3Verify
pkg-config answers and the install succeeds.
pkg-config --libs mysqlclient
python -c "import MySQLdb"Confirmed by github.com
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 mysql2Fix
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 mysqlclient3Verify
The import prints version info.
python -c "import MySQLdb; print(MySQLdb.version_info)"Confirmed by github.com
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:
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
Related fixes
Databases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
pip cannot build the mariadb package because mariadb_config is missing
Please make sure, that MariaDB Connector/C is installed on your system.
The mariadb Python package builds against MariaDB Connector/C, and it finds the library through the mariadb_config program.
3 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
Django cannot load MySQLdb and asks whether mysqlclient is installed
Error loading MySQLdb module: Did you install mysqlclient or MySQL-python?
Django's MySQL backend imports MySQLdb, which is provided by the mysqlclient package.
3 causes, each with a fixDatabases
python manage.py migrate finishes but the tables for my app are missing
relation "myapp_book" does not exist
migrate only applies migration files that exist.
3 causes, each with a fixDatabases
An EC2 instance cannot reach its RDS database
Could not open connection to the host, on port <port>: Connect failed
RDS denies all access until a security group allows it.
3 causes, each with a fix