gem install mysql2 fails while building the native extension
ERROR: 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.
Fix it fast
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 --verbose2Match what you see, then jump to its fix
- 1
The build cannot find mysql.h or the MySQL client library, on LinuxThe MySQL client development package is not installedFix - 2
The linker reports it cannot find -lssl or -lcrypto on macOSmacOS has no linkable OpenSSLFix - 3
The manual gem install works, but bundle install still failsBundler builds the gem without the optionFix - 4
The 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
- 1
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.h2Fix
Install the development package for your distribution, then install the gem again.
sudo apt install libmysqlclient-dev
gem install mysql23Verify
The gem installs and loads.
ruby -e 'require "mysql2"; puts Mysql2::VERSION'Confirmed by github.com
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@32Fix
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
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.mysql22Fix
Store the build option for the gem in Bundler's config.
bundle config --local build.mysql2 -- --with-openssl-dir=$(brew --prefix openssl@3)
bundle install3Verify
bundle install finishes.
bundle exec ruby -e 'require "mysql2"; puts :ok'Confirmed by github.com
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_config2Fix
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_config3Verify
The gem installs and loads.
ruby -e 'require "mysql2"; puts Mysql2::VERSION'Confirmed by github.com
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
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fixBack end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fixBack end
AWS SDK for PHP rejects requests: the signature is from the future
Signature not yet current: {date} is still later than {date}
AWS compares the timestamp in your signed request with its own clock.
2 causes, each with a fixBack 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 fixBack 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