Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

pip install mysqlclient fails on Alpine: Can not find valid pkg-config name

ErrorException: 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.

  • Applies to Alpine 3.22, Python 3.13, mysqlclient 2.2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1All four pkg-config --exists attempts fail one after anotherThe development package that ships the .pc file is not installedFix
    2. 2which pkg-config prints nothing inside the imagepkg-config itself is missingFix

What does the error look like?

  • Exception: Can not find valid pkg-config name.
  • Specify MYSQLCLIENT_CFLAGS and MYSQLCLIENT_LDFLAGS env vars manually
  • Trying 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/pkgconfig

2Fix

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 mysqlclient

3Verify

The check from the first step now prints a found line, and pip finishes.

docker build -t app .

Confirmed by pkgs.alpinelinux.org

Did this fix it?

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

2Fix

Alpine ships the /usr/bin/pkg-config command in the pkgconf package. Add it to the apk line.

RUN apk add --no-cache pkgconf

3Verify

The command now resolves.

pkg-config --version

Confirmed by pkgs.alpinelinux.org

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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