macOSで「/Library/Ruby/Gemsへの書き込み権限がありません」を修正する

TL;DR

macOSにはシステム用のRubyが同梱されていますが、Appleが意図的に書き込みを禁止しています。最善の方法は、rbenvまたはHomebrewを使ってRubyをインストールし、Appleのシステムルービーではなく、自分専用のRubyを使用することです。今すぐ動かしたい場合は、後述の--user-installの回避策に直接進んでください。

エラーの詳細

ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.

このエラーは、シェルが/usr/bin/ruby（macOSに同梱されているRuby）を指しているときに発生します。そのディレクトリはrootが所有しており、System Integrity Protection（SIP）によって保護されています。重要な点として、sudo gem installも解決策にはなりません。新しいmacOSバージョンでは、完全に失敗するか、後々厄介な問題を引き起こす中途半端な状態になることがあります。

なぜこのエラーが起きるのか

AppleはRubyを独自の組み込みツール向けの便宜として含めており、ユーザーが管理するランタイムとして提供しているわけではありません。macOS Catalina以降、システムパーティションはほとんどの領域で読み取り専用になっています。SIPはroot権限があってもシステム所有のディレクトリへの書き込みをブロックします。

/usr/bin/rubyのバイナリは2.6.x系で止まっています。現在の安定版が3.3.x系であることを考えると、Rubyとしては非常に古いバージョンです。これはもともと開発用として使われることを想定していません。新しいターミナルで以下のコマンドを実行して、現在の状況を確認してください：

$ which ruby
/usr/bin/ruby

$ ruby -v
ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin23]

ここで/usr/bin/rubyと表示されている場合、実行するすべてのgem installでこのエラーが発生します。

解決策1：rbenvをインストールする（推奨）

rbenvはシステムファイルに触れることなく、複数のRubyバージョンを並行して管理できます。Macで本格的なRuby開発を行う際の標準的なセットアップです。一度設定すれば、Ruby 3.1、3.2、3.3の切り替えがコマンド一つで済みます。

手順1 — HomebrewでrbenvをインストールするStep 1 — Install rbenv via Homebrew

# Homebrewがない場合はまずインストールする
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 次にrbenvをインストールする
brew install rbenv ruby-build

手順2 — シェルにrbenvを追加する

zsh（Catalina以降のデフォルトシェル）の場合：

echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc

bashの場合：

echo 'eval "$(rbenv init - bash)"' >> ~/.bash_profile
source ~/.bash_profile

手順3 — Rubyのバージョンをインストールする

# 利用可能なバージョンを確認する
rbenv install -l

# 特定のバージョンをインストールする（例：3.3.3）
rbenv install 3.3.3

# グローバルのデフォルトとして設定する
rbenv global 3.3.3

手順4 — 確認してgemをインストールする

$ which ruby
/Users/yourname/.rbenv/shims/ruby

$ ruby -v
ruby 3.3.3 (2024-06-12 revision f1a0099d0b) [arm64-darwin23]

# これでgem installがエラーなく動作する
gem install bundler

解決策2：Homebrew Rubyを直接使用する

複数のRubyバージョンを管理する必要がない場合は、HomebrewでRubyをインストールしてPATHをそちらに向けるだけです。rbenvより設定が少なくシンプルです。

brew install ruby

HomebrewのRubyがシステムのRubyより優先されるよう、PATHを設定します：

# 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

新しいターミナルウィンドウを開いて、設定が反映されているか確認します：

$ which ruby
/opt/homebrew/opt/ruby/bin/ruby

$ gem install bundler   # パーミッションエラーなし

解決策3：応急処置 — ホームディレクトリにインストールする

今すぐgemを使いたいけどRubyの環境設定に手を付けられない場合は、--user-installフラグを使うとシステムディレクトリを完全に回避し、代わりに~/.gemにインストールできます：

gem install bundler --user-install

gemはホームディレクトリに配置されますが、シェルがそのバイナリを見つけられるようにPATHに追加する必要があります：

echo 'export PATH="$(ruby -r rubygems -e "puts Gem.user_dir")/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

個人スクリプトには問題ありません。ただし、他のメンバーと共有するプロジェクトやCIで実行する場合は混乱を招く可能性があります。ユーザーのgemパスは他のメンバーのマシンには存在しないためです。

やってはいけないこと：sudo gem install は使わない

パーミッションエラーが出たとき、反射的にsudoを付けたくなるものです。しかしmacOSのRuby gemでは、それは間違いです：

SIPが書き込みをブロックする場合があります。または部分的に成功して、gemの状態が壊れてしまうこともあります。
rootとしてインストールされたgemは、後でユーザー管理のRubyに切り替えたときに競合を引き起こします。
シェルは依然としてシステムRubyを指したまま。根本原因は解決されていません。

完全に避けてください。

PATHが正しく読み込まれているか確認する

上記のいずれかの方法で修正した後、ターミナルウィンドウを完全に閉じて新しく開いてください。タブを新しく開くだけでは不十分です。タブは古いシェルセッションを引き継ぐため、更新された設定が反映されません。その後、以下を実行してください：

$ which ruby
# /usr/bin/ruby であってはならない

$ gem env home
# ホームディレクトリまたはHomebrewのプレフィックス内を指しているはず
# 例：/Users/yourname/.rbenv/versions/3.3.3/lib/ruby/gems/3.3.0

$ gem install bundler
# Gem::FilePermissionError なしで完了するはず

ヒント

このエラー以外のファイルパーミッションのデバッグ（ディレクトリの所有権の確認、適切なchmod値の調査、数値モードとシンボリックモードの変換など）には、ToolCraftのUnix Permissions Calculatorが計算の手間を省いてくれます。8進数の値で迷うことが多い方はブックマークしておく価値があります。

rbenvのセットアップが完了したら、.ruby-versionファイルでプロジェクトレベルのRubyバージョンを固定しておきましょう：

echo "3.3.3" > .ruby-version

rbenvはプロジェクトにcdしたときにこのファイルを自動的に読み込みます。チーム全員とCIパイプラインが、調整の手間なく同じRubyバージョンで動作するようになります。

まとめ

このエラーはmacOSのシステムRubyに書き込もうとしたことが原因です。Appleが意図的にロックしています。
最善の解決策：rbenvまたはHomebrew RubyをインストールしてPATHを更新する。
応急処置：gem install <gem> --user-installを使ってホームディレクトリにインストールする。
macOSでsudo gem installは使わないこと。症状を回避するだけで、根本原因はそのまま残ります。
修正後は新しいターミナルを開き、which rubyを実行して/usr/bin/rubyでないことを確認する。