Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

gem install mysql2 fails while building the native extension

ErrorERROR: Failed to build gem native extension.

Short answer

The mysql2 gem compiles against the MySQL client library, so the build needs its development headers. On Linux install a libmysqlclient or libmariadb dev package. On macOS install OpenSSL with Homebrew and pass its directory to the build. Read the first failing line of the build output.

  • Applies to Ruby 3.3, mysql2 0.5, Ubuntu 24.04, macOS 15
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the install with verbose output and read the first failing line. A missing header or library points at the first cause, a linker error on macOS at the second.

    gem install mysql2 --verbose
  2. 2Match what you see, then jump to its fix

    1. 1The build cannot find mysql.h or the MySQL client library, on LinuxThe MySQL client development package is not installedFix
    2. 2The linker reports it cannot find -lssl or -lcrypto on macOSmacOS has no linkable OpenSSLFix
    3. 3The manual gem install works, but bundle install still failsBundler builds the gem without the optionFix
    4. 4The log says it could not find mysql_config or the MySQL directory, and MySQL is installed somewhere customThe build cannot find a client library in the default placesFix

What does the error look like?

  • ERROR: Failed to build gem native extension.

Cause 1 of 4

The MySQL client development package is not installed

1Check

The gem needs the headers, not only the shared library. The README names libmariadb-dev, libmysqlclient-dev, mysql-devel and default-libmysqlclient-dev depending on the distribution.

ls /usr/include/mysql/mysql.h

2Fix

Install the development package for your distribution, then install the gem again.

sudo apt install libmysqlclient-dev
gem install mysql2

3Verify

The gem installs and loads.

ruby -e 'require "mysql2"; puts Mysql2::VERSION'

Confirmed by github.com

Did this fix it?

Cause 2 of 4

macOS has no linkable OpenSSL

1Check

Recent macOS does not ship an OpenSSL that can be linked. The README asks for OpenSSL 3 from Homebrew, the same family your Ruby and the MySQL client use.

brew --prefix openssl@3

2Fix

Install the command line tools and OpenSSL, then pass the OpenSSL directory after the double dash.

xcode-select --install
brew install openssl@3 zstd
gem install mysql2 -- --with-openssl-dir=$(brew --prefix openssl@3)

3Verify

The gem installs and loads.

ruby -e 'require "mysql2"; puts Mysql2::VERSION'

Confirmed by github.com

Did this fix it?

Cause 3 of 4

Bundler builds the gem without the option

1Check

Bundler does not reuse arguments you gave to gem install.

bundle config get build.mysql2

2Fix

Store the build option for the gem in Bundler's config.

bundle config --local build.mysql2 -- --with-openssl-dir=$(brew --prefix openssl@3)
bundle install

3Verify

bundle install finishes.

bundle exec ruby -e 'require "mysql2"; puts :ok'

Confirmed by github.com

Did this fix it?

Cause 4 of 4

The build cannot find a client library in the default places

1Check

Without options the gem looks for mysql_config in typical paths, then /usr/local.

which mysql_config

2Fix

Tell it where MySQL lives. --with-mysql-dir uses lib and include under that directory; --with-mysql-config asks the given mysql_config binary instead. The two options exclude each other.

gem install mysql2 -- --with-mysql-config=/path/to/mysql_config

3Verify

The gem installs and loads.

ruby -e 'require "mysql2"; puts Mysql2::VERSION'

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Put the client dev package in your Dockerfile or provisioning script so builds do not depend on a laptop.
  • Keep the Bundler build option in the project's config for the whole team on macOS.
  • Use the same OpenSSL 3 family for Ruby and the MySQL client.

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?

Related fixes

Back end

CodeIgniter 4 cannot write its cache files

CodeIgniter\Cache\Exceptions\CacheException: Cache unable to write to /var/www/app/writable/cache/

CodeIgniter 4's file cache needs a cache directory that the web server can really write to.

2 causes, each with a fix

Back end

CodeIgniter 3 loads the model but the property is undefined

The model name you are loading is the name of a resource that is already being used: user

CodeIgniter 3 expects a model file named like its class, with the first letter capitalised, for example User_model.php holding class User_model.

2 causes, each with a fix

Next step

Want this handled for good?

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