Ruby mysql2 gem "libmysqlclient not found" in CI

The mysql2 gem compiles a C extension that links against the MySQL/MariaDB client library. When the client -dev package is absent, mkmf cannot find libmysqlclient and the native build fails before make even runs.

What this error means

Installing mysql2 fails with "Cannot find the MySQL client library" or "libmysqlclient is missing", pointing at mysql_config or the client -dev package as the missing piece.

checking for mysql_query() in -lmysqlclient... no
checking for main() in -lm... yes
-----
libmysqlclient is missing. You may need to 'apt-get install
libmysqlclient-dev' or 'yum install mysql-devel'.
-----

Common causes

The MySQL client -dev package is not installed

mysql2 needs the client development library (libmysqlclient-dev or default-libmysqlclient-dev). Without it the linker check fails.

mysql_config is not on PATH

The gem uses mysql_config to locate the library; if it is missing or in a non-standard path, the build cannot find the client.

How to fix it

Install the client development library

Provide the MySQL/MariaDB client -dev package before bundle install.

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y default-libmysqlclient-dev
bundle install --jobs 4

Point the gem at mysql_config if non-standard

If the client lives in a custom prefix, pass its mysql_config to the gem build.

bundle config build.mysql2 \
  "--with-mysql-config=/usr/local/mysql/bin/mysql_config"
bundle install

How to prevent it

• Install the MySQL client -dev package in CI before native gem installs.
• Use a runner image that bundles the database client libraries you compile against.
• Document the system dependencies mysql2 requires for new runners.

Related guides