pip install mysqlclient fails on a Mac
pip install mysqlclient ends with a build error on macOSShort answer
mysqlclient is a C extension, so pip compiles it against the MySQL client library and finds that library with pkg-config. On a Mac, the build fails when the library or pkg-config is not installed, or when pkg-config cannot see Homebrew's keg-only mysql-client. Install both with Homebrew and point PKG_CONFIG_PATH at the client.
Fix it fast
1Find out which cause you have
Scroll up in the pip output to the first error line. It says whether pkg-config, the library or the compiler is the problem.
pip install mysqlclient 2>&1 | tail -n 402Match what you see, then jump to its fix
- 1
The log mentions pkg-config or mysql_config being not foundMySQL client library or pkg-config is not installedFix - 2
You installed mysql-client to avoid the full server and the build still cannot find the libraryOnly mysql-client is installed, and pkg-config cannot see itFix - 3
The build starts but the compiler or linker cannot find mysql headers or librariespkg-config is present but gives wrong flagsFix
- 1
What does the error look like?
pip install mysqlclient ends with a build error on macOSThe build output mentions pkg-config or the MySQL client library
Cause 1 of 3
MySQL client library or pkg-config is not installed
1Check
The build runs pkg-config --cflags --ldflags mysqlclient by default, so it needs pkg-config and the client library.
which pkg-config
brew list | grep -E 'mysql|pkg-config'2Fix
Install them with Homebrew, then install the package again.
brew install mysql pkg-config
pip install mysqlclient3Verify
pip prints Successfully installed mysqlclient.
python -c 'import MySQLdb; print(MySQLdb.version_info)'Confirmed by raw.githubusercontent.com
Cause 2 of 3
Only mysql-client is installed, and pkg-config cannot see it
1Check
Homebrew's mysql-client is not linked into the default path, so point pkg-config at its folder before building.
ls "$(brew --prefix)/opt/mysql-client/lib/pkgconfig"2Fix
Set PKG_CONFIG_PATH to that folder for the install.
brew install mysql-client pkg-config
export PKG_CONFIG_PATH="$(brew --prefix)/opt/mysql-client/lib/pkgconfig"
pip install mysqlclient3Verify
The wheel builds and the import works.
python -c 'import MySQLdb'Confirmed by raw.githubusercontent.com
Cause 3 of 3
pkg-config is present but gives wrong flags
1Check
You can bypass pkg-config by passing the flags yourself.
pkg-config mysqlclient --cflags; pkg-config mysqlclient --libs2Fix
Set MYSQLCLIENT_CFLAGS and MYSQLCLIENT_LDFLAGS to the output of those two commands before pip install.
export MYSQLCLIENT_CFLAGS="$(pkg-config mysqlclient --cflags)"
export MYSQLCLIENT_LDFLAGS="$(pkg-config mysqlclient --libs)"
pip install mysqlclient3Verify
The install completes.
pip show mysqlclientConfirmed by raw.githubusercontent.com
How do I stop it coming back?
- Put the Homebrew install and PKG_CONFIG_PATH line into your project setup notes.
- Use a virtual environment per project so a failed build does not touch other work.
- If you do not need the C driver, pure-Python PyMySQL avoids compiling.
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
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
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
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
MySQL error 3159: connections using insecure transport are prohibited
ER_SECURE_TRANSPORT_REQUIRED
Error 3159 means the server has require_secure_transport turned on and your client connected over plain TCP.
3 causes, each with a fixDatabases
pip install mysqlclient fails to build on Windows, Linux or macOS
error: metadata-generation-failed
mysqlclient is a C extension.
3 causes, each with a fixDatabases
pandas read_sql fails with Execution failed on sql ... sqlite_master on a MySQL connection
Execution failed on sql 'SELECT name FROM sqlite_master WHERE type='table' AND name=?;'
pandas supports a plain DBAPI connection only for sqlite3.
3 causes, each with a fix