Fix: Ignoring ffi Gem Extensions Not Built Error in CocoaPods

Fix: Ignoring ffi Gem Extensions Not Built Error in CocoaPods

Written by

in

Quick answer: This error occurs because the ffi gem’s native extensions weren’t compiled, often due to macOS system Ruby permission restrictions. Fix it by installing CocoaPods via Homebrew (recommended) or installing ffi with –user-install and adding it to your PATH.

Why this happens

The error Ignoring ffi-1.13.1 because its extensions are not built appears when the ffi (Foreign Function Interface) gem fails to compile its native C extensions during installation. On macOS, the system Ruby (/usr/bin/ruby) installs gems into /Library/Ruby/Gems/2.6.0, which requires root write permissions. When you run gem install cocoapods or gem pristine ffi without sudo, the build step for native extensions silently fails, leaving the gem in a broken state.

CocoaPods depends on ffi to interact with Xcode’s project files. If ffi can’t load its compiled bundle, CocoaPods commands crash or emit this warning. The follow-up Gem::FilePermissionError confirms you’re trying to write to the system Ruby directory without elevated privileges.

How to fix it

1. Install CocoaPods via Homebrew (recommended)

Homebrew bundles its own Ruby and isolates gems from the system Ruby, avoiding permission issues entirely. This is now the preferred installation method per the CocoaPods team.

brew install cocoapods

If Homebrew reports that CocoaPods is already installed but not linked, force the link:

brew link --overwrite cocoapods

Verify the installation:

pod --version
# Should print something like 1.15.2

2. Install ffi with –user-install (alternative)

If you prefer managing gems yourself or cannot use Homebrew, install the specific ffi version into your user directory and ensure its binaries are on your PATH.

gem install ffi --version 1.13.1 --user-install

Add the user gem bin directory to your shell profile. For zsh (default on macOS Catalina and later):

echo 'export PATH=$HOME/.gem/ruby/2.6.0/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

For bash users, append to ~/.bash_profile or ~/.bashrc instead. Adjust the Ruby version segment (2.6.0) if your system Ruby differs — check with ruby -v.

After updating the PATH, run the pristine command to rebuild extensions:

gem pristine ffi --version 1.13.1

Then install CocoaPods:

gem install cocoapods --user-install

How to prevent it

  • Use Homebrew for CocoaPods — it handles Ruby versioning and gem isolation automatically.
  • Avoid sudo gem install — modifying the system Ruby directory breaks macOS updates and creates permission conflicts.
  • Consider a Ruby version manager (rbenv, chruby, asdf) if you work on multiple projects needing different Ruby/gem versions.
  • Keep Homebrew updated (brew update && brew upgrade) so CocoaPods stays compatible with new Xcode releases.

FAQ

Why does gem pristine fail with a permission error?

gem pristine attempts to rebuild the gem’s native extensions in the original install location (/Library/Ruby/Gems/2.6.0). That directory is owned by root, so a regular user cannot write to it. Using --user-install or Homebrew sidesteps this by using a writable directory.

Can I just run sudo gem pristine ffi --version 1.13.1?

It works temporarily, but it’s discouraged. Writing to the system Ruby directory can conflict with macOS updates, break other tools that expect a clean system Ruby, and create inconsistent environments across team members’ machines.

Do I need to uninstall the broken gem first?

No. gem pristine rebuilds extensions in place, and gem install --user-install places a separate, functional copy in your home directory that takes precedence once your PATH is updated. The broken system copy remains but is ignored.

Related fixes

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.