How to Install mysqlclient in CI Without Build Failures

By Kaveh Alemi·Latchkey

mysqlclient is a C extension that links against the MySQL/MariaDB client library, and the build fails the moment mysql_config or the headers are missing.

Unlike many database drivers, mysqlclient does not ship a prebuilt wheel for every platform, so CI usually compiles it from source. That needs the MySQL client dev package, pkg-config, and a compiler. Install those, or switch to a pure-Python driver if you can.

Why it fails in CI

The mysqlclient build calls mysql_config (or pkg-config) to locate libmysqlclient and its headers, then compiles a C extension. Slim runner images have none of that, so the build aborts immediately.

• Exception: Can not find valid pkg-config name. / mysql_config: not found.
• OSError: mysql_config not found during the build step.
• fatal error: Python.h: No such file or directory - Python headers missing.

Install it reliably

Install the MySQL/MariaDB client dev package plus pkg-config and a compiler before pip. On Debian/Ubuntu the metapackage default-libmysqlclient-dev pulls in the right client library. If you do not specifically need the C driver’s speed, the pure-Python PyMySQL needs no build at all.

# Debian/Ubuntu: client headers + pkg-config + compiler
apt-get update && apt-get install -y \
  default-libmysqlclient-dev build-essential pkg-config python3-dev
pip install mysqlclient

# No build needed: pure-Python driver
pip install PyMySQL

Cache & speed

Bake default-libmysqlclient-dev and pkg-config into the runner image so you are not running apt on every job, and cache the pip cache. The compile is quick once the headers are present.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-mysql-${{ hashFiles('requirements*.txt') }}

Common errors

Verify it actually works

• Assert on the restored content, not on the step succeeding. A cache or download step commonly reports success while producing an empty directory.
• Key any cache to the exact tool and dataset version. A cache restored across a version boundary is worse than a cold start.
• Check the size against the runner disk budget; GitHub-hosted runners ship roughly 14 GB free and a large dataset exhausts it as unrelated write errors.

Key takeaways

• mysqlclient compiles from source; it needs the MySQL client headers.
• Install default-libmysqlclient-dev + pkg-config + build-essential.
• PyMySQL is a pure-Python alternative that needs no build.

Frequently asked questions

Related guides

References

• GitHub Actions documentation