CocoaPodsは、iOS・macOSアプリが使う外部ライブラリを、Podfileという1枚のファイルで宣言して取り込む依存管理ツールです。2026年10月時点の最新版は1.17.0ですが、ライブラリの公開先である「trunk」は2026年12月2日に新規登録の受け付けを恒久的に止める予定で、使い方と同じくらい「この先どこまで使えるか」が問われる段階に入りました。この記事では、1.17.0を実際にインストールしてpod installを回した結果をもとに、仕組みと基本操作、よく出るエラー、読み取り専用化の後に残るものと止まるものを整理します。
まとめ：CocoaPodsの要点（2026年10月時点）
- CocoaPodsはRuby製の依存管理ツール。Podfileに書いたライブラリ（Pod）を取得し、Pods.xcodeprojと.xcworkspaceを生成してアプリに結び付けます。
- 最新版は1.17.0（2026年7月6日公開）。前の1.16.2から約1年8か月空いており、プロジェクトは2024年8月からメンテナンスモードと明言しています。
- macOS標準のRuby 2.6では、gem installがそのままでは通りません。Mac向けのビルド済みffiがRuby 3.0以上を要求するため、Homebrewか新しいRubyで入れます。
- pod installはPodfile.lockの版を守り、pod updateだけが版を上げます。PodfileとPodfile.lockは必ずバージョン管理に入れます。
- 2026年12月2日にtrunkが読み取り専用化。既存の版は引き続き取得できますが、trunk経由の新しい版は届かなくなります。Firebaseは2026年10月7日公開の13.0.0からCocoaPodsでの配布を終了しました。
- 新規開発はSwift Package Manager、既存アプリは依存ごとに移行計画。CocoaPodsを続けるのは、移行先の無い依存が残る間だけと考えるのが現実的です。
まず、PodfileからXcodeへ依存を組み込む流れを確認します。
CocoaPodsの仕組み｜Podfile・Podspec・trunkとXcodeへの組み込み方
Podfile・Podspec・trunkの役割分担
CocoaPodsは3つの部品で動いています。アプリ側が「何を使うか」を書くのがPodfile、ライブラリ側が「自分は何者で、どのソースをどうビルドするか」を書くのがPodspec、公開されたPodspecを収録するカタログがGitHubのCocoaPods/Specsリポジトリで、そこへの登録と作者の認証を受け持つサービスがtrunkです。Podfile.lockではこの公開カタログ自体もtrunkという名前で表示されます。pod installを実行すると、CocoaPodsはPodfileの条件に合う版をこのカタログのPodspecから探し、ソースを取得します。
カタログの読み方は1.8で変わりました。以前は巨大なSpecsリポジトリをまるごとgit cloneしていましたが、1.8からhttps://cdn.cocoapods.org/が既定の取得元になり、必要なPodの索引だけをCDNから引く方式になっています。初回のpod installで表示されるAdding spec repo `trunk` with CDNという行がそれです。
pod installがXcodeプロジェクトに加える変更
pod installは、Podsディレクトリの中にPods.xcodeprojを作り、アプリの.xcodeprojとPods.xcodeprojを束ねる.xcworkspaceを生成します。以後は.xcworkspaceを開いてビルドします。.xcodeprojを直接開くとPodが見つからずリンクエラーになるのは、この束ね方のためです。
アプリ側のプロジェクトにも手が入ります。CocoaPodsを外すコマンドpod deintegrateの出力を見ると、何が足されていたかがわかります。1.17.0の実行結果は次のとおりでした。
$ pod deintegrate
Deintegrating `Demo.xcodeproj`
Deleted 1 'Check Pods Manifest.lock' build phases.
Deleted 1 'Embed Pods Frameworks' build phases.
- Pods_Demo.framework
- Pods-Demo.release.xcconfig
- Pods-Demo.debug.xcconfig
Deleted 1 empty `Pods` groups from project.
Removing `Pods` directory.この例では、ビルドフェーズ2本（Podfile.lockとの整合確認、フレームワークの埋め込み）と、構成ごとのxcconfig、まとめ用のフレームワークが入ります。ビルド設定を手で上書きすると、このxcconfigとの優先順位で警告が出るので、アプリ側の設定はCocoaPodsの値を継承するように調整し、生成されたxcconfigは直接編集しません。Pod側のビルド設定を変更する必要がある場合は、Podfileのpost_installフックなどで変更を再適用できる形にします。
CocoaPods 1.17.0のインストール手順｜Ruby・Homebrew・pod install
Rubyの選び方とインストール方法
CocoaPods 1.17.0のgemが宣言する必要Rubyは2.6以上です。ところが、macOS 26.6.2に標準で入っているRuby 2.6.10でgem install cocoapods -v 1.17.0を実行すると、2026年10月9日時点では次のエラーで止まりました。
ERROR: Error installing cocoapods:
ffi requires Ruby version >= 3.0, < 4.1.dev. The current ruby version is 2.6.10.210.CocoaPods本体の条件は満たしていても、RubyGemsが選んだ依存先ffi 1.17.4のMac向けビルド済み版（x86_64-darwin・arm64-darwin）が、Ruby 3.0以上4.1未満を条件にしているためです。ソースからビルドする版はRuby 2.5以上で入りますが、Cコンパイラの用意が要るうえ、2.6自体がサポートの終わったRubyです。標準Rubyにsudoで入れる古い手順は、今はそのままでは通りません。現実的な入れ方は次の2つです。
- Homebrew：
brew install cocoapods。2026年10月時点のformulaは1.17.0で、HomebrewのRubyを依存として引き込みます。個人の開発機ならこれが最短です。 - 新しいRuby＋gem：rbenvやmiseでRuby 3系以上を入れ、
gem install cocoapods。チームで版をそろえるなら、Gemfileにgem 'cocoapods', '1.17.0'と書き、bundle exec pod installで実行します。bundle execを付け忘れると、Gemfileの固定を無視してマシンに入っている版が動きます。
Homebrew版のRuby 4.0.6でも1.17.0は動作しました。端末の文字エンコーディングがUTF-8でない場合は警告が出ます。その場合は、シェル設定でexport LANG=en_US.UTF-8などのUTF-8ロケールを設定します。
pod initからpod installまでの初回セットアップ
Xcodeでプロジェクトを作ったら、.xcodeprojのあるディレクトリでpod initを実行します。ひな形のPodfileができるので、対象OSと使うPodを書き足します。例として、HTTP通信のAlamofireとレイアウト用のSnapKitを入れるPodfileです。
platform :ios, '16.0'
target 'Demo' do
use_frameworks!
pod 'Alamofire', '~> 5.10'
pod 'SnapKit', '~> 5.7'
enduse_frameworks!は、この例ではPodを動的フレームワークとして組み込む指定です。Swift製Podでも必須ではなく、静的ライブラリとしての組み込みも可能なので、採用するPodの要件に合わせて指定します。pod installの出力は次のとおりです。CDNの索引をまだ取得していない状態からの初回実行は、timeコマンドで約13秒でした（通信環境とキャッシュの状態で変わります）。
$ pod install
Analyzing dependencies
Adding spec repo `trunk` with CDN `https://cdn.cocoapods.org/`
Downloading dependencies
Installing Alamofire (5.12.2)
Installing SnapKit (5.7.1)
Generating Pods project
Integrating client project
[!] Please close any current Xcode sessions and use `Demo.xcworkspace` for this project from now on.
Pod installation complete! There are 2 dependencies from the Podfile and 2 total pods installed.最後の警告どおり、以後はopen Demo.xcworkspaceで開きます。作業ディレクトリにはPodfile.lock、Podsディレクトリ、Demo.xcworkspaceの3つが増えています。
Podfile.lockとpod install／pod updateの使い分け
Podfile.lockに記録される内容と版指定の読み方
Podfileに書くのは「5.10以上」のような条件で、実際にどの版を入れたかはPodfile.lockに残ります。上の例で生成されたPodfile.lockの全文です。
PODS:
- Alamofire (5.12.2)
- SnapKit (5.7.1)
DEPENDENCIES:
- Alamofire (~> 5.10)
- SnapKit (~> 5.7)
SPEC REPOS:
trunk:
- Alamofire
- SnapKit
SPEC CHECKSUMS:
Alamofire: c5f37d8f438dc1d7fd3ff767f2f80fd01ca381d7
SnapKit: d612e99e678a2d3b95bf60b0705ed0a35c03484a
PODFILE CHECKSUM: fa4bdcf40d02e535bc6fadf8f02279ea0d8924d4
COCOAPODS: 1.17.0PODSが確定した版、DEPENDENCIESがPodfileの条件、SPEC REPOSが取得元です。~>は「指定した版以上で、右から2番目の数字を1つ上げた版の手前まで」という意味で、~> 5.10は5.10以上6.0未満、~> 5.10.0なら5.10.0以上5.11未満になります。条件を~> 5.10と書いても5.12.2が入ったのは、6.0未満で最新だったからです。
pod installとpod updateの挙動の違い（実測）
pod installは、Podfile.lockに記録済みのPodを新しい版に上げません。pod updateだけが条件内で最新版を取りに行きます。これを確かめるため、いったんAlamofireを'5.10.2'に固定してインストールし、条件を'~> 5.10'に戻してから再実行しました。
$ pod install # 条件を ~> 5.10 に戻した後
Installing Alamofire 5.10.2
$ pod outdated
- Alamofire 5.10.2 -> 5.12.2 (latest version 5.12.2)
$ pod update Alamofire
Installing Alamofire 5.12.2 (was 5.10.2)条件の上では5.12.2を入れられるのに、pod installはロックされた5.10.2を維持しました。チームの誰がいつpod installしても同じ版がそろうのは、この挙動のおかげです。使い分けは単純で、Podを追加・削除したときと、clone直後はpod install、版を上げたいときだけpod update Pod名です。名前を付けずにpod updateを打つと全Podが一斉に上がり、どの更新で壊れたのかを追えなくなるので、更新はPodを指定して1つずつ行います。
PodfileとPodsディレクトリのバージョン管理
公式ガイドは、Podsディレクトリをコミットするかどうかを「プロジェクト次第」としたうえで、PodfileとPodfile.lockはどちらの方針でも必ずバージョン管理に入れるよう求めています。Podsをコミットすると、cloneしてすぐビルドでき、取得元のリポジトリが消えても困りません。代わりにリポジトリが大きくなり、版の違うブランチをマージするたびにPodsの衝突を解くことになります。
判断基準は、取得元が消えたときの影響の大きさです。公開ソースのリポジトリが削除されると、読み取り専用化の前後を問わず取得に失敗する可能性があります。Podsのコミットや許諾範囲内のミラー保存で、外部の取得元だけに依存しない構成にできます。長く保守するアプリで、ソースを外部リポジトリから取るPodが多く、作者の更新が止まっているものも含むなら、Podsのコミットに寄せる方が安全です。
pod installが失敗するときの代表的なエラーと対処
1.17.0で実際に再現したメッセージと、ソースコード上の出し元から整理しました。
| メッセージ（先頭） | 主な原因 | 対処 |
|---|---|---|
Unable to find a specification for |
索引が古い／指定誤り／取得元不足 | 指定・取得元を確認し、索引が古ければpod install --repo-update |
CDN: trunk URL couldn't be downloaded |
CDNへの接続失敗 | プロキシ確認後に再実行 |
could not find compatible versions |
版の条件が衝突 | 制約を確認し、lockの固定が原因ならpod update Pod名 |
The sandbox is not in sync |
Pods側とlockの不一致 | pod install |
may not be compatible with |
対象OSが低すぎる（警告） | platformを引き上げ |
1行目は、新しく公開された版や初めて使うPodが手元の索引に無い場合などに出ます。メッセージ自体が原因を3つ挙げます。
[!] Unable to find a specification for `NoSuchPodXyz12417`
You have either:
* out-of-date source repos which you can update with `pod repo update` or with `pod install --repo-update`.
* mistyped the name or version.
* not added the source repo that hosts the Podspec to your Podfile.3つ目は社内用のSpecsリポジトリを使う場合で、Podfileにsource行が足りないときです。読み取り専用化の後に自前のSpecsリポジトリでPodを配る場合も、このsource指定を使います。Gitリポジトリやローカルパスを直接指定する配布方法もあります。
「sandbox is not in sync」はビルド時に出るエラーで、pod installが追加したビルドフェーズ「Check Pods Manifest.lock」が、Podfile.lockとPods/Manifest.lockの食い違いを検出したものです。ブランチを切り替えた後や、lockだけをpullした後にpod installを忘れると出ます。CIでは、ビルドの前に必ずpod installを走らせる手順にしておくと防げます。
最後の行は止まらない警告です。Podfileでplatform :ios, '9.0'にすると、Alamofire 5.12.2の最低要件iOS 10.0に届かないという警告が出たまま、インストール自体は完了しました。インストール完了は、そのOSでのビルドや実行の成功を保証しません。PodfileのplatformとXcodeのDeployment Targetを、採用するPodの対応範囲に合わせて確認します。
2026年12月2日のtrunk読み取り専用化で止まるものと動き続けるもの
trunk読み取り専用化の日程と影響範囲
CocoaPodsのOrta Therox氏が2024年11月30日に公表し、2025年5月に更新したtrunk読み取り専用化の計画では、2026年11月1日から7日にテスト運用を行い、12月2日にtrunkが新しいPodspecの受け付けを恒久的に停止します。以後、trunkには新しいPodも既存Podの新しい版も追加されません。
止まるのは「新規の登録」だけです。計画は、Specsリポジトリと配信用CDNはGitHubとjsDelivrが続く限り動き続け、既存のビルドはすべて動くと明記しています。自社運用のSpecsリポジトリを使う場合や、依存をすべて手元に置いている場合も影響を受けません。つまり、12月2日を境に既存アプリのビルドが壊れるわけではなく、trunk経由のセキュリティ修正や新機能が届かなくなることが本当の影響です。なお2025年5月からは、セキュリティ研究者による悪用を理由に、prepare_commandを使う新規Podの登録がすでに止められています。
主要SDK・フレームワークの対応状況
依存する側の動きは、読み取り専用化の日付より前に始まっています。
| 対象 | CocoaPodsの扱い | 時期 |
|---|---|---|
| Firebase（Apple向けSDK） | v12が最後、13.0.0から配布終了 | 2026年10月7日 |
| Flutter | SwiftPMが既定、未対応プラグインはCocoaPodsへ | 3.44から |
| React Native | CocoaPodsが既定、SwiftPMは試験的 | 0.87時点 |
| RxSwift | CocoaPodsサポートを非推奨化 | 6.10.0から |
Firebaseは、読み取り専用化より2か月早い10月に公開を止めた理由を「レジストリが固まる前に最終版を安定させるため」と移行ガイドで説明しています。v12以前の版はCocoaPodsから取得でき続けますが、13.0.0以降はSwift Package Managerかバイナリ配布でしか受け取れません。Flutter 3.44は自動で移行を進め、プラグインがSwiftPMに未対応のときだけCocoaPodsに戻ります。React Nativeは0.87でも公式ブログが「CocoaPodsが既定でサポートされる経路」と明記しており、iOSのビルドにRubyとCocoaPodsが要る状態がまだ続きます。React Nativeのアプリでは、React Native FirebaseのようにFirebaseを包むライブラリから先に影響が出る点に注意してください。
CocoaPods本体のメンテナンス状況
2024年8月13日の方針表明でCocoaPodsは自らをメンテナンスモードと位置付け、trunkの重大なセキュリティ問題への対応と、Xcodeの更新に追随するため年2回以上のリリースを目指すとしました。実際のリリースは、1.16.2（2024年10月31日）の次が1.17.0（2026年7月6日）で、約1年8か月空いています。1.17.0の変更も、pod repo pushへの--no-lint追加、xcodeprojの最低版を1.28.0へ引き上げ、active_supportの特定版でのクラッシュ修正など保守的なものです。新しいXcodeで不具合が出ても、修正版がすぐ出るとは限らない前提で計画を立てるべきです。
CocoaPodsを使い続けるか移行するかの判断基準
使い続けてよいケースと移行を急ぐべきケース
結論から言うと、必要な依存がすべてSwift Package Managerに対応している新規のネイティブiOSアプリなら、CocoaPodsを選ぶ理由はありません。Xcodeに統合されたSwift Package Managerで足り、RubyもGemfileも要らないからです。既存アプリについては、依存の中身で判断が分かれます。
当面使い続けてよいのは、Podの大半がすでに更新の止まった枯れたライブラリで、版を上げる予定がないアプリです。読み取り専用化の後も既存版は取得でき、ビルドは続きます。React Nativeのように、フレームワーク自体がCocoaPodsを既定にしている場合も、フレームワーク側の移行を待つのが筋です。
移行を急ぐべきなのは、Firebaseや決済・認証SDKのようにセキュリティ修正を受け続ける必要がある依存を持つアプリです。Firebaseは13.0.0（2026年10月7日）からCocoaPodsでの配布を終えており、他のSDKも12月2日以降はtrunkに新版を載せられません。各提供元の告知で、CocoaPods向けの最終版がどれかを確認してください。旧版に留まり続けると、App Storeの審査要件やOSの仕様変更に追随した修正を取り込めなくなります。逆に失敗しやすいのは、移行先の無いPodが1つでも残ったまま全面移行を始めるパターンです。Firebaseの移行ガイドも、同じターゲットでCocoaPodsとSwift Package Managerを混在させると依存の循環やビルドエラーにつながると注意しています。先に全依存のSwiftPM対応を洗い出し、未対応が残るものは手動導入や代替ライブラリに置き換える目処を立ててから着手します。
pod deintegrateで外したあとに手で消すもの
移行の第一歩は、Xcodeを閉じてからpod deintegrateでプロジェクトからCocoaPodsの痕跡を外すことです。前述の出力の続きには、次の注意が出ます。
Project has been deintegrated. No traces of CocoaPods left in project.
Note: The workspace referencing the Pods project still remains.実行後もディレクトリにはPodfile、Podfile.lock、.xcworkspaceが残ります。.xcworkspaceを開いたままにすると、存在しないPods.xcodeprojを参照して混乱するので、CocoaPodsを完全に外す場合はPodfileとPodfile.lockを削除します。.xcworkspaceはCocoaPods専用に生成されたものだけを削除し、その場合は以後.xcodeprojを開きます。既存の複数プロジェクトや共有設定を含むワークスペースは残し、Podsへの参照だけを取り除きます。そこから先のSwift Package Managerへの依存追加、Package.resolvedの扱い、併用期間の進め方はSwift Package Manager入門で手順を解説しています。
よくある質問
CocoaPodsは2026年12月以降使えなくなりますか？
既存のPodfileでのpod installとビルドは続けられます。12月2日に止まるのはtrunkへの新しいPodや新しい版の登録で、公開済みの版はCDNから取得できる計画です。ただし、trunkで配られているライブラリの修正版はそれ以降届かないため、セキュリティ修正が必要な依存から順にSwift Package Managerなどへ移す必要があります。
Podfileとは何ですか？
アプリが使うPodと対象OS、ターゲットを宣言するRuby記法のテキストファイルです。pod initでひな形を作り、pod 'Alamofire', '~> 5.10'のように1行に1つずつ書きます。実際に入った版はPodfileではなくPodfile.lockに記録されます。
CocoaPodsのバージョンを確認するには？
手元にインストールされている版はpod --versionで確認できます。プロジェクトが最後にどの版でpod installされたかは、Podfile.lock末尾のCOCOAPODS:行に残ります。両者がずれているとlockの書式差分が出やすいので、チームではGemfileで版を固定してbundle exec pod installで実行します。
pod repo updateは毎回必要ですか？
毎回は不要です。CDN方式では必要なPodの索引だけを取りに行くため、通常のpod installで足ります。公開されたばかりの版が見つからない、またはUnable to find a specificationが出たときに、pod install --repo-updateで索引を更新してから再実行します。
自作のPodは12月2日以降どこで公開できますか？
trunkには公開できなくなるので、社内やチーム向けなら自前のSpecsリポジトリを用意し、pod repo pushで登録してPodfileのsource行で参照します。1.17.0ではpod repo pushにLintを省く--no-lintオプションが加わりました。不特定多数に配るライブラリなら、Swift Package Managerでの配布に切り替えるのが現実的です。
