How to install the mysql2 Ruby gem on a Mac M1

The mysql2 Ruby gem is a critical dependency for many Ruby on Rails applications that use MySQL as their database. However, installing this gem on a Mac powered by Apple Silicon (M1 chip) can present unique challenges due to architecture compatibility and linked libraries. Fortunately, with a few steps and careful preparation, you can get the mysql2 gem running smoothly on your M1 Mac.

In this article, you'll learn how to overcome the common installation issues and configure your development environment for success.

Why the Mac M1 Requires Special Attention

The Apple M1 chip runs on ARM architecture, which differs from the traditional Intel x86. While Rosetta 2 bridges many gaps, software that interacts with native libraries—like the mysql2 gem—might require special configuration.

That's why installing mysql2 isn't always as simple as running gem install mysql2. Missing headers, incorrect architecture paths, or linking problems with MySQL can cause the installation to fail.

Step-by-Step Guide to Installing mysql2 on Mac M1

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

1. Install Homebrew (if not already installed)

If you haven’t already done so, install Homebrew, the package manager for macOS.

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

After installation, make sure to add Homebrew to your shell profile. For ZSH:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

2. Install MySQL via Homebrew

To ensure compatibility, install MySQL using Homebrew rather than downloading it from the MySQL website.

brew install mysql

This will install MySQL with the correct libraries and headers for ARM architecture.

3. Export Paths (Optional but Often Needed)

Sometimes, the gem installer can’t find the MySQL configuration files. You can explicitly set the path using environment variables when installing:

gem install mysql2 -- --with-mysql-config=/opt/homebrew/bin/mysql_config

This tells the compiler where to find the MySQL configuration and helps avoid annoying errors like:

mkmf.rb can't find header files for ruby

4. Use Rosetta 2 (When Necessary)

If you’re still having trouble, try installing your gem within a terminal running under Rosetta. This can help in situations where dependencies are only available for Intel-based architecture.

1. Find your Terminal app in Finder (Applications > Utilities)
2. Right-click and choose Get Info
3. Check the box that reads “Open using Rosetta“

Then rerun the install command inside the new terminal session:

gem install mysql2 -- --with-mysql-config=/opt/homebrew/bin/mysql_config

Image not found in postmeta

5. Troubleshooting Tips

If you're still encountering errors, consider the following checks:

• Are Command Line Tools installed? Run xcode-select --install
• Is your Ruby version compatible? Consider using a Ruby version manager like RVM or rbenv.
• Is MySQL correctly linked? Run brew link mysql if needed.

Some developers also report success when reinstalling Ruby using Homebrew under Rosetta to match the architecture expected by native extensions.

A Final Note on Native Dependencies

Working with native gems like mysql2 on Apple Silicon does require some know-how, but once you get the environment set up correctly, everything functions as expected. macOS and toolchain developers are also constantly improving support for M1 chips, making future installations even simpler.

Good luck coding! With your mysql2 gem installed, your Rails app on M1 is one step closer to greatness.