Skip to content
BSWEN
Blog

How to resolve can't find header files for ruby error when install cocoapods in macos

Cowrie
Cowrie
Dev @ Bswen

Problem

When installing cocoapods on macOS using the following command:

Terminal window
sudo gem install cocoapods

The following error occurs:

Terminal window
Fetching: concurrent-ruby-1.1.7.gem (100%)
Successfully installed concurrent-ruby-1.1.7
...
ERROR:  Error installing cocoapods:
  ERROR: Failed to build gem native extension.


    current directory: /Library/Ruby/Gems/2.3.0/gems/ffi-1.13.1/ext/ffi_c
/System/Library/Frameworks/Ruby.framework/Versions/2.3/usr/bin/ruby -r ./siteconf20201011-18064-1amwcon.rb extconf.rb
mkmf.rb can't find header files for ruby at /System/Library/Frameworks/Ruby.framework/Versions/2.3/usr/lib/ruby/include/ruby.h


extconf failed, exit code 1

The error indicates that the Ruby header files are missing, which prevents the installation of the ffi gem, a dependency for cocoapods.

Environment

  • macOS 10.14
  • Ruby 2.3.7p456 (2018-03-28 revision 63024) [universal.x86_64-darwin18]
  • Gem 2.5.2.3

Reason

The root cause of this issue is that Xcode 11 ships with the macOS 10.15 SDK, which includes headers for Ruby 2.6 but not for macOS 10.14’s Ruby 2.3. This mismatch causes the mkmf.rb script to fail when trying to locate the Ruby header files.

To verify the issue, check the Ruby configuration:

Terminal window
ruby -rrbconfig -e 'puts RbConfig::CONFIG["rubyhdrdir"]'

This command outputs a directory path that does not exist:

Terminal window
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.3/usr/include/ruby-2.3.0

Solution

To resolve this issue, update the Ruby configuration to point to the correct SDK path:

Terminal window
sudo xcode-select --switch /Library/Developer/CommandLineTools

After running this command, verify the updated Ruby header directory:

Terminal window
ruby -rrbconfig -e 'puts RbConfig::CONFIG["rubyhdrdir"]'

The output should now point to the correct path:

Terminal window
/Library/Developer/CommandLineTools/SDKs/MacOSX10.14.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.3/usr/include/ruby-2.3.0

Now, retry installing cocoapods:

Terminal window
sudo gem install cocoapods

The installation should proceed without errors.

The Last Step

After successfully installing cocoapods, restore the original Xcode settings:

Terminal window
sudo xcode-select --switch /Applications/Xcode.app

Summary

This post walked through the steps to resolve the “can’t find header files for ruby” error when installing cocoapods on macOS. The issue arises due to a mismatch between the Ruby version and the SDK headers provided by Xcode. By updating the Ruby configuration to point to the correct SDK path, the installation process can proceed smoothly. Remember to restore the original Xcode settings after completing the installation to avoid unintended side effects.

Final Words + More Resources

My intention with this article was to help others who might be considering solving such a problem. So I hope that’s been the case here. If you still have any questions, don’t hesitate to ask me by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Tags: