MySQL client library issues on OS X El Capitan

Oct 1st, 2015   10:07 pm

Apple’s latest OS X version, v10.11 “El Capitan”, comes with a new security feature protecting core system files called “System Integrity Protection” (SIP). All sounds good in theory, but software that uses, or expects files to be in, the core system directories, like /usr/lib, can run in to permission issues.

I ran in to this issue when running a Ruby on Rails project that uses MySQL.

Library not loaded: libmysqlclient.18.dylib (LoadError)

There are two solutions to this, widely offered online. One is to use the DYLD_LIBRARY_PATH environment variable to point to the MySQL-installed lib folder (e.g. /usr/local/mysql-5.6.27-osx10.8-x86_64/lib). However, that doesn’t work for me (and many other OS X users).

Second is to create a symlink in /usr/lib to the library in the MySQL install folder. However, because of SIP, even root can not add that symlink in /usr/lib. Getting nowhere, quick, with the environment variables, I looked more in to the symlink approach. The good news is that you can temporarily disable SIP to create the symlink. This is not an ideal fix, because of the security risk, but it does work! Here’s what I did.

  1. Restart the Mac in Recovery mode, by holding down Cmd+R from boot (until you see the Apple logo)
  2. Under the “Utilities” menu, launch the terminal. In the terminal type csrutil disable to (temporarily disable SIP), and type reboot to reboot the Mac in to regular mode
  3. Open a terminal and create the symlink: sudo ln -s /usr/local/mysql/lib/libmysqlclient.18.dylib /usr/lib (note that /usr/local/mysql is in itself symlinked to the install folder (a new install at the time of writing was created in /usr/local/mysql-5.6.27-osx10.8-x86_64 for example)
  4. Restart in Recovery mode again, launch the terminal and re-enable SIP again with csrutil enable, and reboot

There you have it. Temporarily disabling SIP might not be the ideal solution, but it did get it working again!

One other solution is to use install_name_tool. I couldn’t get it to work for the Rails app (but that might be down to not referencing the right Gem path). I did get it to work for the installed PERL DBD mysql module. Example usage:

sudo install_name_tool -change libmysqlclient.18.dylib \
/usr/local/mysql/lib/libmysqlclient.18.dylib \

That works for El Capitan’s latest (at time of writing) version of PERL (5.18). Use man install_name_tool for the details, but the first line references the system name for the shared dylib, the second line references the actual path to the dylib, and the third line is the path to the bundled dylib you want to update.