How to install the mysql2 Ruby gem on a Mac M1

Installing the mysql2 Ruby gem on a Mac M1 can be a little tricky due to architecture differences and native dependencies. However, with careful steps and the right development environment, you can get the mysql2 gem working smoothly on your Apple Silicon machine. This guide will walk you through the process using the most reliable and up-to-date methods available in 2024.

Why is Installation Difficult on Apple M1?

The primary issue stems from the M1 chip’s ARM-based architecture, which differs from the Intel-based applications that many open-source gems and libraries have been traditionally built for. In addition, the mysql2 gem depends on native MySQL client libraries, which may not be available out of the box.

Fortunately, Apple provides Rosetta 2 for Intel compatibility, and Homebrew supports both ARM and x86 architectures, making it possible to build and use native libraries with the right approach.

Step-by-Step Installation Instructions

Follow these steps carefully to install the mysql2 gem on your M1 Mac.

1. Install Homebrew (if not already installed)

Homebrew is the de facto package manager for macOS. Open a terminal and run the command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

If you’re on an M1 Mac, Homebrew will be installed under /opt/homebrew. You can check this with:

brew --prefix

2. Install MySQL using Homebrew

Install the MySQL database server and client libraries with:

brew install mysql

Once installed, add the MySQL binary path to your shell profile if it’s not already there:

echo 'export PATH="/opt/homebrew/opt/mysql/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

This ensures Ruby will locate the correct MySQL client libraries during gem installation.

3. Install the Required MySQL Client Headers

The mysql2 gem requires access to MySQL’s C client header files and libraries. Point the gem installer to where Homebrew has stored them using environment variables:


export LDFLAGS="-L/opt/homebrew/opt/mysql/lib"
export CPPFLAGS="-I/opt/homebrew/opt/mysql/include"
export PKG_CONFIG_PATH="/opt/homebrew/opt/mysql/lib/pkgconfig"

You can add these to your ~/.zshrc to make them permanent.

4. Install Ruby and the mysql2 Gem

If you haven’t installed Ruby through a version manager like rbenv or rvm, it’s highly recommended:

Install rbenv: brew install rbenv
Add rbenv initialization to shell: echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
Install desired Ruby version: rbenv install 3.2.2 (for example)
Set global version: rbenv global 3.2.2

Then, make sure that bundle is installed:

gem install bundler

Now you can finally install the mysql2 gem with the correct flags:

gem install mysql2 -- --with-ldflags="-L/opt/homebrew/opt/mysql/lib" \
--with-cppflags="-I/opt/homebrew/opt/mysql/include"

5. Troubleshooting Common Errors

If you encounter errors such as “can’t find mysql client library,” make sure:

You’ve pointed to the correct /opt/homebrew/opt/mysql paths
Your shell profile is sourcing those environment variables
You’ve restarted your terminal session after making changes

It’s also worth checking whether your Ruby environment is running under Rosetta if you’re using Intel-native binaries. However, for most modern setups, staying pure ARM and installing native ARM binaries is more efficient and stable.

Verifying the Installation

Once the installation completes without errors, you can test the gem:

ruby -rmysql2 -e 'puts Mysql2::Client.new(host: "localhost", username: "root").server_info'

This command attempts to open a connection using the default root user. Make sure MySQL is running and properly configured to accept connections from your account.

Conclusion

Setting up the mysql2 gem on a Mac M1 involves more steps than usual, but once you configure the correct path settings and dependencies, the process is repeatable and stable. By using Homebrew, properly configuring environment variables, and using a Ruby version manager, you ensure a clean and robust development environment on your Apple Silicon Mac.

If you regularly develop Ruby applications, consider adding these steps to a personal setup script or documentation file for future reference.