Installing the mysql2 gem became a frequent problem for people who use macOS to develop Ruby1 based apps that utilize MySQL2 as a data store. I’ve personally encountered this problem myself back in the days, and I still encounter it on brand new setup macOS workstations. The error is always some variation of “unable to locate libmysqlclient” or “checking for mysql_config”, and the fix is never about Ruby at all.
In this article, we will go through the steps I took to resolve this problem, which all boil down to one idea: tell the gem where the OpenSSL libraries actually live.
Tradition lives because young people come along who catch its romance and add new glories to it.
~ Michael Novak.
✅ Prerequisites
We assume here you have some basic knowledge on setting up Ruby and command line tools on macOS.
- Ruby (Latest)
- Bundler3 (Latest)
- Homebrew4 (Installed and no problems, run and check
brew doctorfor more info and if the installation is okay)
🔧 What did I do to solve the problem?
Here’s what I’ve done to resolve the problem, three commands and a working gem.
1. Install OpenSSL
First is to install openssl or gnutls (choose your poison). Both are great and have some pros and cons, but most people would use openssl, and that’s what I preferred.
brew install opensslThe core issue is that macOS ships with an old, locked version of OpenSSL that the mysql2 gem does not like. Homebrew’s OpenSSL is newer and complete, and pointing the build at it fixes the whole chain.
2. Point the Gem at Homebrew OpenSSL
Then we point the mysql2 dependency to the installed openssl package from Homebrew.
bundle config --global build.mysql2 --with-opt="$(brew --prefix openssl)"The --with-opt flag tells the gem’s native extension where to find the OpenSSL headers and libraries. Using brew --prefix means you never hardcode a path that changes when Homebrew upgrades.
3. Install the Gem
Of that, we install the mysql2 dependency and all the sub-dependents that are needed.
bundle installBundler picks up the build configuration we just set and compiles mysql2 against the correct OpenSSL. This time, the compilation succeeds, and all the gems that depend on it install cleanly as well.
That’s all needed to install mysql2 on a fresh macOS Mojave. Now you can develop a Ruby app that utilizes MySQL as a data store.
🧠 Final Thoughts
So, guys, let me know if you encounter any problems, or any additional ways to install mysql2. The pattern here is worth remembering beyond this one gem: whenever a native gem fails to build on macOS, the cause is almost always a missing or mismatched system library, and the fix is almost always pointing the build at Homebrew’s version.
OpenSSL, readline, libxml2, the list goes on, and the --with-opt trick works for all of them. That’s it guys, hope you enjoyed this article and as always live life.
😀😁😁🤣😃😄
- Ruby is an interpreted, high-level, general-purpose programming language. It was designed and developed in the mid-1990s by Yukihiro “Matz” Matsumoto in Japan. Ruby is dynamically typed and uses garbage collection. ↩︎
- MySQL is an open-source relational database management system. Its name is a combination of “My”, the name of co-founder Michael Widenius’s daughter, and “SQL”, the abbreviation for Structured Query Language. ↩︎
- Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed. ↩︎
- Homebrew is a free and open-source software package management system that simplifies the installation of software on Apple’s macOS operating system and Linux. The name is intended to suggest the idea of building software on the Mac depending on the user’s taste. ↩︎