Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

pip install mysqlclient fails on a Mac

Errorpip install mysqlclient ends with a build error on macOS

Short 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.

  • Applies to macOS, Homebrew, Python 3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 40
  2. 2Match what you see, then jump to its fix

    1. 1The log mentions pkg-config or mysql_config being not foundMySQL client library or pkg-config is not installedFix
    2. 2You 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. 3The build starts but the compiler or linker cannot find mysql headers or librariespkg-config is present but gives wrong flagsFix

What does the error look like?

  • pip install mysqlclient ends with a build error on macOS
  • The 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 mysqlclient

3Verify

pip prints Successfully installed mysqlclient.

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

Confirmed by raw.githubusercontent.com

Did this fix it?

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 mysqlclient

3Verify

The wheel builds and the import works.

python -c 'import MySQLdb'

Confirmed by raw.githubusercontent.com

Did this fix it?

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 --libs

2Fix

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 mysqlclient

3Verify

The install completes.

pip show mysqlclient

Confirmed by raw.githubusercontent.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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