pip install mysqlclient fails on Alpine: Can not find valid pkg-config name
Exception: Can not find valid pkg-config name.Short answer
mysqlclient's build script runs pkg-config and tries four names: mysqlclient, mariadb, libmariadb and perconaserverclient. On Alpine none exist until you install pkgconf, a compiler toolchain and mariadb-dev. Install those before pip, keep the runtime library in the final image, or set the two flag variables yourself.
Fix it fast
1Find out which cause you have
Run the exact check the build script runs, in the same image. The first name that exits 0 is what mysqlclient will use.
docker run --rm python:3.13-alpine sh -c \ 'for p in mysqlclient mariadb libmariadb perconaserverclient; do pkg-config --exists $p && echo "found $p"; done; echo done'2Match what you see, then jump to its fix
What does the error look like?
Exception: Can not find valid pkg-config name.Specify MYSQLCLIENT_CFLAGS and MYSQLCLIENT_LDFLAGS env vars manuallyTrying pkg-config --exists mysqlclient
Cause 1 of 2
The development package that ships the .pc file is not installed
1Check
On Alpine the file mariadb.pc comes from mariadb-dev, and libmariadb.pc from mariadb-connector-c-dev. Without one of them, the script finds no name.
ls /usr/lib/pkgconfig2Fix
Install pkgconf (it provides the pkg-config command), the build tools and mariadb-dev before running pip.
RUN apk add --no-cache pkgconf build-base mariadb-dev
RUN pip install --no-cache-dir mysqlclient3Verify
The check from the first step now prints a found line, and pip finishes.
docker build -t app .Confirmed by pkgs.alpinelinux.org
Cause 2 of 2
pkg-config itself is missing
1Check
The build script calls pkg-config through a shell. The mysqlclient README lists pkg-config next to the compiler and headers on Debian, and the same need applies on Alpine.
which pkg-config2Fix
Alpine ships the /usr/bin/pkg-config command in the pkgconf package. Add it to the apk line.
RUN apk add --no-cache pkgconf3Verify
The command now resolves.
pkg-config --versionConfirmed by pkgs.alpinelinux.org
How do I stop it coming back?
- Use a multi-stage build: compile in a stage with build-base and mariadb-dev, run in a stage with only mariadb-connector-c.
- Pin the Alpine tag so package names do not move under you.
- Keep the pip install and the apk add in the same Dockerfile stage so the packages are there when pip builds.
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
pip install cryptography tries to compile and fails in a Docker build
fatal error: 'openssl/aes.h' file not found
cryptography ships prebuilt wheels.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Import of python_2_unicode_compatible fails after upgrading Django
Code importing django.utils.six fails on Django 3.0 and later
Django 3.0 removed the leftover Python 2 helpers, including python_2_unicode_compatible and django.utils.six.
2 causes, each with a fix