TL;DR
macOS ships with a system Ruby you can't write to — Apple locked it intentionally. Your best move is installing Ruby through rbenv or Homebrew so you're working with your own copy, not Apple's. Need something working in the next two minutes? Jump straight to the --user-install workaround below.
The exact error
ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.
This fires when your shell is pointing at /usr/bin/ruby — the Ruby bundled with macOS. That directory is root-owned and guarded by System Integrity Protection (SIP). Importantly, sudo gem install won't save you either. On newer macOS versions it either fails outright or half-succeeds in ways that cause headaches down the line.
Why this happens
Apple includes Ruby as a convenience for its own built-in tools, not as a runtime you're supposed to manage. Since macOS Catalina, the system partition is read-only in most areas. SIP blocks writes to system-owned directories even with root access.
The /usr/bin/ruby binary is frozen at 2.6.x — ancient by Ruby standards, given the current stable release is 3.3.x. It was never meant to be the Ruby you develop with. Run this in a fresh terminal to confirm where you stand:
$ which ruby
/usr/bin/ruby
$ ruby -v
ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin23]
Seeing /usr/bin/ruby there means every gem install you run will hit this error.
Fix 1: Install rbenv (Recommended)
rbenv manages multiple Ruby versions side-by-side without touching system files. It's the standard setup for anyone doing serious Ruby work on a Mac — once it's in place, switching between Ruby 3.1, 3.2, and 3.3 is a single command.
Step 1 — Install rbenv via Homebrew
# Install Homebrew first if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Then install rbenv
brew install rbenv ruby-build
Step 2 — Add rbenv to your shell
For zsh (the default shell since Catalina):
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc
For bash:
echo 'eval "$(rbenv init - bash)"' >> ~/.bash_profile
source ~/.bash_profile
Step 3 — Install a Ruby version
# See available versions
rbenv install -l
# Install a specific version (e.g., 3.3.3)
rbenv install 3.3.3
# Set it as the global default
rbenv global 3.3.3
Step 4 — Verify and install gems
$ which ruby
/Users/yourname/.rbenv/shims/ruby
$ ruby -v
ruby 3.3.3 (2024-06-12 revision f1a0099d0b) [arm64-darwin23]
# Now gem install works without errors
gem install bundler
Fix 2: Use Homebrew Ruby directly
Don't need to juggle multiple Ruby versions? Just install Ruby through Homebrew and point your PATH at it. Fewer moving parts than rbenv.
brew install ruby
Wire up your PATH so Homebrew's Ruby takes precedence over the system one:
# Apple Silicon (M1/M2/M3/M4)
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Intel Mac
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Open a fresh terminal window and confirm it took:
$ which ruby
/opt/homebrew/opt/ruby/bin/ruby
$ gem install bundler # No permission error
Fix 3: Quick workaround — install to your home directory
Need gems working right now and can't touch your Ruby setup? The --user-install flag bypasses the system directory entirely by dropping everything into ~/.gem instead:
gem install bundler --user-install
The gems land in your home directory, but your shell won't find their binaries until you add them to PATH:
echo 'export PATH="$(ruby -r rubygems -e "puts Gem.user_dir")/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Fine for personal scripts. On a project shared with others or running through CI, this will cause confusion — your user gem path doesn't exist on their machines.
What NOT to do: avoid sudo gem install
The reflex when something fails with a permission error is to slap sudo in front of it. With Ruby gems on macOS, that's a mistake:
- SIP can still block the write — or let it partially succeed, leaving you with a broken gem state.
- Gems installed as root will conflict later when you switch to a user-managed Ruby.
- Your shell is still pointed at system Ruby. The root cause is untouched.
Skip it entirely.
Confirm your PATH is loading correctly
After any fix above, open a brand new terminal window — full quit and reopen, not just a new tab. Tabs inherit the old shell session and won't pick up your updated config. Then run:
$ which ruby
# Should NOT be /usr/bin/ruby
$ gem env home
# Should point somewhere inside your home directory or Homebrew prefix
# e.g., /Users/yourname/.rbenv/versions/3.3.3/lib/ruby/gems/3.3.0
$ gem install bundler
# Should complete without Gem::FilePermissionError
Tips
For debugging file permissions beyond this specific error — checking directory ownership, figuring out the right chmod value, converting between numeric and symbolic modes — the Unix Permissions Calculator on ToolCraft saves the mental math. Worth bookmarking if you find yourself guessing octal values.
Once rbenv is set up, pin your Ruby version at the project level with a .ruby-version file:
echo "3.3.3" > .ruby-version
rbenv picks this up automatically when you cd into the project. Everyone on the team — and your CI pipeline — runs the same Ruby version without any coordination overhead.
Summary
- The error comes from trying to write to macOS system Ruby — Apple locked it on purpose.
- Best fix: install rbenv or Homebrew Ruby and update your PATH.
- Quick fix: use
gem install <gem> --user-installto install into your home directory. - Don't use
sudo gem installon macOS — it sidesteps the symptom but leaves the cause intact. - After fixing, open a fresh terminal and run
which rubyto confirm you're off/usr/bin/ruby.