CocoaPodsとは？iOS依存管理の仕組みからSPM移行まで完全ガイド【2026年版】

iOS・macOSアプリを開発していると、HTTP通信・画像キャッシュ・UIコンポーネントなど、外部ライブラリを組み込みたい場面が頻繁に訪れます。手動でソースコードをダウンロードしてプロジェクトへ追加する方法は、バージョン管理やアップデート対応が煩雑になりがちです。CocoaPods（ココアポッズ）は、こうしたライブラリの取得・更新・依存解決を自動化するパッケージマネージャです。

2011年にEloy Durán氏によって公開され、10万6,000件以上のライブラリが登録、300万を超えるアプリで採用されています（出典: CocoaPods公式サイト）。Rubyで実装されており、RubyGemsのgem installコマンド、またはHomebrewからインストールできます。

ただし2024年8月にメンテナンスモードへ移行し、2026年12月2日にtrunkリポジトリがread-only（読み取り専用）化される予定です（出典: CocoaPods Blog）。後継としてApple純正のSwift Package Manager（SPM）への移行が推奨されています。

本記事ではCocoaPodsの基礎から導入手順、チーム開発での運用ノウハウ、そして2026年以降を見据えたSPMへの移行戦略までをまとめています。

CocoaPodsが担う役割

CocoaPodsは、Xcodeプロジェクトに外部ライブラリを統合する工程を一元管理します。具体的には以下の処理を自動で行います。

依存解決: ライブラリAがライブラリBに依存している場合、Bも自動で取得
バージョン管理: Podfileに記述したバージョン制約に基づき、互換性のあるバージョンを選定
ビルド設定の統合: ヘッダ検索パス・リンクフラグ・フレームワーク設定をXcodeプロジェクトへ自動反映
ワークスペース生成: .xcworkspaceファイルを作成し、メインプロジェクトとPodsプロジェクトを統合

手動管理と比較した場合の違いを整理します。

作業	手動管理	CocoaPods
ライブラリ取得	GitHubからZIP/cloneで手動取得	`pod install`で自動取得
依存関係の解決	再帰的に自分で調査・追加	Podfileの記述だけで自動解決
バージョン更新	ファイル差し替え＋ビルド設定修正	`pod update`で一括更新
ビルド設定	Build Settings/Build Phasesを手動編集	自動構成
チーム共有	手順書が必要	Podfile + Podfile.lockで再現可能

macOSへのインストール方法

CocoaPodsをインストールする方法は、Homebrew経由とgem経由の2通りがあります。

Homebrewを使う場合

Homebrewがインストール済みのmacOSであれば、ターミナルで以下を実行します。

brew install cocoapods

Homebrewはシステムのrubyに依存せずCocoaPodsをインストールできるため、権限周りのトラブルが少ない方法です。

RubyGems（gem）を使う場合

macOSにプリインストールされているRubyを利用する方法です。

sudo gem install cocoapods

macOS Sonoma以降ではシステムRubyの制約が強化されているため、rbenvやasdfでユーザー領域のRubyを用意してから実行する方が安定します。

# rbenv経由の例
rbenv install 3.3.0
rbenv global 3.3.0
gem install cocoapods

インストール確認とセットアップ

# バージョン確認
pod --version
# 例: 1.16.2

# 初回のみSpecsリポジトリをクローン
pod setup

pod setupはCocoaPods Specsリポジトリ（全Podspecのマスターデータ）をローカルにクローンします。CDN経由のキャッシュが普及した現在では省略可能ですが、オフライン環境で作業する場合は実行しておくと安心です。

Xcodeプロジェクトへの導入手順

1. Podfileを生成する

Xcodeプロジェクト（.xcodeproj）があるディレクトリへ移動し、pod initを実行します。

cd ~/Projects/MyApp
pod init

Podfileというテキストファイルが生成されます。

2. Podfileを編集する

テキストエディタでPodfileを開き、利用したいライブラリを追記します。

platform :ios, '16.0'

target 'MyApp' do
  use_frameworks!

  pod 'Alamofire', '~> 5.9'
  pod 'Kingfisher', '~> 8.0'
  pod 'SwiftyJSON', '~> 5.0'
end

platform :ios, '16.0' — 対象プラットフォームと最低バージョン
use_frameworks! — 動的フレームワークとしてビルド（Swift利用時は必須）
pod 'ライブラリ名', 'バージョン指定' — インストール対象

3. ライブラリを取得する

pod install

初回実行時は以下の処理が行われます。

Podfileに記述された各ライブラリの依存関係を解決
ソースコードをダウンロード
Pods/ディレクトリにライブラリを配置
MyApp.xcworkspaceを生成
Podfile.lockを生成

4. .xcworkspaceで開く

**pod install実行後は、.xcodeprojではなく.xcworkspaceからXcodeを開きます。**これを忘れると「Module not found」エラーが発生します。

open MyApp.xcworkspace

Podfileのバージョン指定構文

Podfileではセマンティックバージョニングに基づく柔軟なバージョン指定が可能です。

記法	意味	例
`'5.9.1'`	完全一致	5.9.1のみ
`'~> 5.9'`	5.9以上 6.0未満（悲観的制約）	5.9.0, 5.9.1, 5.10.0 等
`'~> 5.9.1'`	5.9.1以上 5.10.0未満	5.9.1, 5.9.2 等
`'>= 5.0'`	5.0以上のすべて	5.0, 6.0, 7.0 等
`'>= 5.0', '< 6.0'`	5.0以上 6.0未満	5.x系すべて
指定なし	最新バージョン	リリース時点の最新

最も多用されるのは ~>（チルダ＋大なり、通称「悲観的バージョン制約」）です。マイナーバージョンアップは許容しつつ、メジャーバージョンの破壊的変更を防ぐバランスの取れた指定方法です。

Podfile応用構文

platform :ios, '16.0'

# ソース指定（プライベートリポジトリの場合）
source 'https://github.com/自社/Specs.git'
source 'https://cdn.cocoapods.org/'

target 'MyApp' do
  use_frameworks!

  pod 'Alamofire', '~> 5.9'

  # Gitリポジトリから直接取得
  pod 'SomePrivateLib', :git => 'https://github.com/example/SomePrivateLib.git', :branch => 'main'

  # ローカルパスから取得（開発中のライブラリ向け）
  pod 'MyLocalLib', :path => '../MyLocalLib'

  # テストターゲット専用のライブラリ
  target 'MyAppTests' do
    inherit! :search_paths
    pod 'Quick', '~> 7.0'
    pod 'Nimble', '~> 13.0'
  end
end

# ビルド後にスクリプトを実行（例: ライセンスファイル生成）
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '16.0'
    end
  end
end

Podfile.lockの役割とチーム開発での運用

pod installを実行すると、Podfile.lockが自動生成されます。このファイルには実際にインストールされた各ライブラリの正確なバージョンが記録されています。

なぜPodfile.lockが重要なのか

Podfileに pod 'Alamofire', '~> 5.9' と書いた場合、条件を満たすバージョンは5.9.0〜5.x.xまで複数存在します。チームメンバーが異なるタイミングでpod installすると、Podfile.lockがなければ別々のバージョンがインストールされてしまう可能性があります。

Podfile.lockをGitリポジトリにコミットしておけば、全員が同じバージョンのライブラリでビルドできます。

運用ルール

ファイル	Gitコミット	役割
`Podfile`	する	依存ライブラリの宣言
`Podfile.lock`	する	確定バージョンの記録
`Pods/` ディレクトリ	プロジェクトによる	ライブラリの実体ファイル

Pods/ディレクトリをGitに含めるかどうかはチームの方針で決まります。含めない場合は.gitignoreに追加し、pod installで復元します。含める場合はリポジトリサイズが増大しますが、CI/CDのセットアップが簡略化されます。

pod installとpod updateの使い分け

この2つのコマンドはよく混同されますが、動作が明確に異なります。

pod install

pod install

Podfile.lockに記録済みのライブラリはロックされたバージョンをインストール
Podfile.lockに存在しない新規追加ライブラリのみ、Podfileの制約に基づいてバージョンを解決
日常的に使うのはこちら

pod update

# 全ライブラリを更新
pod update

# 特定ライブラリのみ更新
pod update Alamofire

Podfile.lockのバージョン記録を無視して、Podfileの制約範囲で最新バージョンを取得
Podfile.lockを上書き更新

判断基準の早見表

場面	使うコマンド
リポジトリをcloneした直後	`pod install`
新しいライブラリをPodfileに追加した	`pod install`
特定ライブラリを最新版に上げたい	`pod update ライブラリ名`
全ライブラリを一括で最新化したい	`pod update`
CI/CDのビルドパイプライン	`pod install`

原則として**pod installを標準コマンドとし、pod updateは意図的なバージョンアップ時のみ**使用します。

代表的なiOSライブラリ

CocoaPodsで提供されている主要ライブラリの一部です。SPM対応状況も併記します。

ライブラリ	用途	SPM対応
Alamofire	HTTP通信	対応済み
Kingfisher	画像キャッシュ・ダウンロード	対応済み
SwiftyJSON	JSONパース	対応済み
SnapKit	Auto Layoutのコードベース記述	対応済み
Realm	モバイルデータベース	対応済み
Firebase	Analytics・Crashlytics・Auth等	対応済み
Lottie	アニメーション描画	対応済み
SDWebImage	画像ダウンロード・キャッシュ	対応済み
R.swift	リソースへの型安全アクセス	対応済み
RxSwift	リアクティブプログラミング	対応済み

2025年時点で主要ライブラリの大半がSPMに対応しています。ただし、一部のObjective-C製ライブラリや社内限定ライブラリはCocoaPodsのみ対応というケースが残っています。

ライブラリの検索にはCocoaPods公式検索ページが利用できます。

よくあるエラーと対処法

`No Podfile found in the project directory`

Podfileが存在しないディレクトリでpod installを実行した場合に発生します。

# 解決: .xcodeprojがあるディレクトリに移動してから実行
cd ~/Projects/MyApp
pod init
pod install

`Unable to find a specification for 'ライブラリ名'`

ライブラリ名のスペルミス、またはSpecsリポジトリが古い場合に発生します。

# ローカルのSpecsキャッシュを更新
pod repo update
pod install

`[!] CocoaPods could not find compatible versions for pod "Firebase"`

依存ライブラリ間でバージョンの競合が起きています。

# Podfile.lockを削除して依存を再解決
rm Podfile.lock
pod install

根本的な解決にはPodfileのバージョン指定を見直し、競合するライブラリのバージョン範囲を調整する必要があります。

`xcrun: error: SDK "iphoneos" cannot be located`

Xcode Command Line Toolsが未設定の場合に発生します。

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

`CDN: trunk Repo update failed`

ネットワーク接続の問題か、CDNサーバーの一時的な障害です。

# CDNをバイパスしてGitHubから直接取得
pod repo remove trunk
pod repo add cocoapods-specs https://github.com/CocoaPods/Specs.git
pod install

2026年12月のread-only化スケジュール

CocoaPodsの公式ブログで発表されたtrunkリポジトリの読み取り専用化計画は、以下のスケジュールで進行しています（出典: CocoaPods Blog）。

時期	内容
2024年8月	メンテナンスモード移行を発表
2025年5月	`prepare_command`を利用した新規Podの追加を停止
2025年中盤〜後半	全Podspec投稿者への通知メール送信
2026年9月〜10月	2回目の警告通知（read-only化まで約1か月）
2026年11月1日〜7日	テスト実施期間（一時的にread-onlyを有効化）
2026年12月2日	trunkリポジトリが恒久的にread-only化

read-only化後に何が変わるか

既存のPodは引き続き利用可能: Specsリポジトリ自体は削除されず、GitHubとjsDelivrが稼働する限りダウンロード可能
新しいPodの公開が不可能に: 新規ライブラリや既存ライブラリの新バージョンをtrunkに登録できなくなる
プライベートSpecsリポジトリは影響なし: 自社運用の独自リポジトリはそのまま利用可能

なぜSPMへ移行すべきなのか

Apple公式ツールであり、Xcodeに統合されている
Rubyやgem等の外部ランタイムが不要
パッケージ解決の速度が高速
Apple自身がFirebase等の大規模SDKをSPM対応に移行済み

CocoaPods・Swift Package Manager・Carthage 機能比較

3つの依存管理ツールの特徴を比較します。

項目	CocoaPods	Swift Package Manager	Carthage
提供元	コミュニティ	Apple	コミュニティ
実装言語	Ruby	Swift	Swift
Xcodeとの統合	ワークスペース経由	Xcode内蔵（GUI対応）	手動リンク
対応言語	Swift / Objective-C	Swift / Objective-C / C / C++	Swift / Objective-C
セットアップ	`gem install` or `brew install`	Xcode同梱（追加不要）	`brew install carthage`
設定ファイル	Podfile（Ruby DSL）	Package.swift（Swiftコード）	Cartfile（テキスト）
ビルド方式	ソースからビルド	ソースからビルド	事前ビルド済みフレームワーク
プライベートリポジトリ	Specs Repo対応	Git URL指定で対応	Git URL指定で対応
登録ライブラリ数	10万6,000以上	個別リポジトリベース	個別リポジトリベース
今後の見通し	2026年12月read-only化	Apple公式で継続開発	メンテナンス縮小傾向
ビルド速度	やや遅い（全Pod再ビルド）	高速（インクリメンタル）	初回のみ遅い（以降キャッシュ）

**新規プロジェクトではSPMが第一選択です。**既存プロジェクトでCocoaPodsを使用している場合も、2026年12月までに移行計画を立てることが推奨されます。

CocoaPodsからSPMへの移行手順（概要）

大規模プロジェクトでの段階的な移行の流れを示します。

ステップ1: SPM対応状況を棚卸しする

現在のPodfileに記載されているライブラリをすべてリストアップし、各ライブラリのGitHubリポジトリでPackage.swiftの有無を確認します。SPM未対応のライブラリがある場合は、代替ライブラリの検討も必要です。

ステップ2: SPM対応ライブラリから順に移行する

Xcodeの「File → Add Package Dependencies…」から、ライブラリのGitリポジトリURLを入力して追加します。追加後、Podfileから該当行を削除し、pod installを再実行します。

ステップ3: SPM未対応ライブラリへの対応

選択肢は3つあります。

ライブラリの開発元にSPM対応をリクエストする（GitHub Issueで依頼）
自前でPackage.swiftを作成し、フォークリポジトリとして管理する
代替ライブラリに切り替える

ステップ4: CocoaPodsを完全に除去する

すべてのライブラリをSPMに移行できたら、以下を実行します。

# CocoaPods関連ファイルを削除
pod deintegrate
rm Podfile
rm Podfile.lock
rm -rf Pods/
rm MyApp.xcworkspace

pod deintegrateはXcodeプロジェクトからCocoaPods由来のビルド設定を除去するコマンドです。実行後は.xcodeprojから直接Xcodeを開けるようになります。

まとめ

CocoaPodsはiOS/macOS開発のライブラリ管理を長年支えてきたツールです。Podfileにライブラリ名とバージョンを記述しpod installを実行するだけで、依存解決からビルド設定の統合までを自動処理します。チーム開発ではPodfile.lockをGitにコミットすることで、メンバー間のバージョン差異を防止できます。

一方で、2026年12月2日にtrunkリポジトリがread-only化される計画が公式に発表されています。既存プロジェクトは引き続き動作しますが、新しいライブラリの追加やバージョン更新が行えなくなるため、Swift Package Managerへの移行を早期に進めることが重要です。

CocoaPodsを新規プロジェクトで採用する場面は少なくなっています。SPMの利用を優先して検討してください
既存プロジェクトでは、SPM対応済みのライブラリから段階的に移行を進めるのが現実的です
SPM未対応のライブラリが残る場合は、2026年12月までに代替手段を確保しておく必要があります

CocoaPodsが担う役割#

macOSへのインストール方法#

Homebrewを使う場合#

RubyGems（gem）を使う場合#

インストール確認とセットアップ#

Xcodeプロジェクトへの導入手順#

1. Podfileを生成する#

2. Podfileを編集する#

3. ライブラリを取得する#

4. .xcworkspaceで開く#

Podfileのバージョン指定構文#

Podfile応用構文#

Podfile.lockの役割とチーム開発での運用#

なぜPodfile.lockが重要なのか#

運用ルール#

pod installとpod updateの使い分け#

pod install#

pod update#

判断基準の早見表#

代表的なiOSライブラリ#

よくあるエラーと対処法#

No Podfile found in the project directory#

Unable to find a specification for 'ライブラリ名'#

[!] CocoaPods could not find compatible versions for pod "Firebase"#

xcrun: error: SDK "iphoneos" cannot be located#

CDN: trunk Repo update failed#

2026年12月のread-only化スケジュール#

read-only化後に何が変わるか#

なぜSPMへ移行すべきなのか#

CocoaPods・Swift Package Manager・Carthage 機能比較#

CocoaPodsからSPMへの移行手順（概要）#

ステップ1: SPM対応状況を棚卸しする#

ステップ2: SPM対応ライブラリから順に移行する#

ステップ3: SPM未対応ライブラリへの対応#

ステップ4: CocoaPodsを完全に除去する#

まとめ#