※この記事は、2026年11月12日に、FlutterとCocoaPodsの公式の情報(ドキュメントと、Flutterのコマンドのソースコード)で確かめた内容です(Flutterの公式ドキュメントは、この時点でFlutter 3.50を前提に書かれています)。コマンドの動き方や出てくる文は、バージョンや環境によって異なります。
「iOSのシミュレーターで動かそうとしたら、pod install で止まった」
「Androidではビルドが通るのに、iOSだけ通らない」
「CocoaPodsの英語のエラーが何十行も出て、どこを読めばいいのかわからない」
「そもそもpod installって、何をしてんねん!?」と言いたくなりますよね。
先に答えを書くと、FlutterのCocoaPodsのエラーは、ログの中にFlutterが出す「Error:」や「Warning:」の行を見れば、原因の種類がだいたいわかります。 Flutterのコマンドは、pod install が失敗すると、その出力を見て、よくある原因なら直し方の案内を付けてくれるからです。
よく出るのは、次の5つの種類です。
- CocoaPodsが入っていない・壊れている・古い
- CocoaPodsのspecs(パッケージの一覧)が古い
- パッケージが求めるiOSの最小バージョンに、アプリが届いていない
- AppleシリコンのMacで、ffiという部品が合っていない
- CocoaPodsのパッケージと、Swift Package Managerのパッケージが食い違っている
ぼくは、もともとAndroidのネイティブ(JavaとKotlin)からアプリ作りに入った人間で、2019年にFlutterに移りました。今は、自社アプリをすべてFlutterで作り、Android版とiOS版の両方をストアに出しています。
(ビルドエラー全体の調べ方は、こちらの記事に順番をまとめていますので、よろしければご覧ください)
もくじ
1. 2026年のFlutterとCocoaPodsの関係
まずは公式の情報から見ていきます。
CocoaPodsは、iOS側のパッケージ(ライブラリ)をプロジェクトに入れるための道具です。Flutterのパッケージのうち、iOSのネイティブのコードを持つものは、これまでCocoaPodsを通して組み込まれてきました。pod install は、その組み込みを実行するコマンドです。
ところが、Flutterの公式ドキュメントでは、次のように書かれています。
- Flutter 3.44から、Swift Package Manager(SwiftPM)への対応が、最初から有効になった。Flutterを上げてアプリを動かすと、SwiftPMの設定が自動で足される
- SwiftPMにまだ対応していないパッケージがあると、そのパッケージは、これまでどおりCocoaPodsで組み込まれる
- FlutterはCocoaPodsへの対応を続けるが、メンテナンスモード(直しはするが、新しいことはしない状態)になっている
- CocoaPodsのレジストリ(パッケージの登録先)は、2026年12月2日に、ずっと読み取り専用になる
CocoaPodsの公式ブログでも、2026年12月2日に、新しいPodspec(パッケージの登録)を受け付けなくする、とされています。そのうえで、今あるビルドは動き続けるように、とも書かれています。ただ、それ以降は、CocoaPodsの登録先を通したパッケージの更新は届かなくなります。
つまり、2026年の今、pod install のエラーに出会うのは、使っているパッケージのどれかが、まだCocoaPodsで組み込まれているときです。古いプロジェクトや、SwiftPMを止めているプロジェクトでも出ます。
SwiftPMを止める方法も、公式ドキュメントには載っています。ただ、「ふつうはやらないでください」と書かれていて、将来は止められなくなる、ともされています。エラーをよけるためにSwiftPMを止めるのは、最後の手にしておくのが無難です。
参考:Swift Package Manager for app developers(Flutter docs、2026年11月12日確認)/CocoaPods Specs Repo(CocoaPods Blog、2026年11月12日確認)
2. Flutterの「Error:」の行で、原因の種類を見分ける
pod install が失敗したときの出力は長いですが、Flutterが付けてくれる案内の文は、決まった形をしています。Flutterのコマンドのソースコード(cocoapods.dart)から、よく出るものを並べると、次のとおりです。
| Flutterが出す文(一部) | 意味 | 見る節 |
|---|---|---|
Warning: CocoaPods not installed. Skipping pod install. | CocoaPodsが入っていない | 3 |
Warning: CocoaPods is installed but broken. Skipping pod install. | 入っているが、動かない | 3 |
Warning: CocoaPods minimum required version ... or greater not installed. | CocoaPodsが古すぎる | 3 |
Error: CocoaPods's specs repository is too out-of-date to satisfy dependencies. | specs(パッケージの一覧)が古い | 4 |
Error: The plugin "..." requires a higher minimum iOS deployment version than your application is targeting. | アプリのiOSの最小バージョンが低い | 5 |
Error: To set up CocoaPods for ARM macOS, run: | AppleシリコンのMacで、ffiが合っていない | 6 |
Error: A dependency conflict has occurred because ... uses CocoaPods while ... uses Swift Package Manager. | CocoaPodsとSwiftPMのパッケージが食い違っている | 7 |
Warning: Podfile is out of date | Podfileの書き方が古い | 7 |
最初に探すのは、この表の左の文です。 CocoaPods自身のエラーの行は、その上にたくさん出ていますが、Flutterの案内の文が見つかれば、どこから手を付ければいいかが決まります。
この表のどれも出ずに、Error running pod install だけで止まっているときは、8の節を見てください。
参考:cocoapods.dart(Flutterのソースコード、2026年11月12日確認)
3. CocoaPodsが入っていない・壊れている・古いとき
Flutterは、pod install の前に、CocoaPodsが使える状態かを確かめています。入っていないときは、pod install を飛ばして、次の案内を出します。
Warning: CocoaPods not installed. Skipping pod install.
CocoaPods is a package manager for iOS or macOS platform code.
Without CocoaPods, plugins will not work on iOS or macOS.「CocoaPodsがないと、iOSやmacOSでプラグイン(パッケージ)が動かない」という意味です。Flutterの公式ドキュメントでも、ネイティブのiOSのコードを使うパッケージのために、最新のCocoaPodsを入れるように書かれています。
入れ方
入れ方は、CocoaPodsの公式のガイドに沿います。ガイドでは、基本のコマンドは次の形です。
gem install cocoapodsmacOSに最初から入っているRuby(システムのRuby)で入れるときは、sudo を付けます。
sudo gem install cocoapodsただし、CocoaPodsの公式のガイドでは、システムのRubyを使うのはおすすめしない、とされています。RVMやrbenvでRubyのバージョンを管理するか、Homebrewで別のRubyを入れる(brew install ruby)方法が挙げられています。sudo を使わずに、自分のユーザーのフォルダに入れる方法も載っています。
入ったかどうかは、バージョンを出して確かめます。
pod --version「broken」と出るとき
Warning: CocoaPods is installed but broken. は、CocoaPodsは入っているのに、pod --version が動かなかったときの案内です。Flutterの案内の文では、CocoaPodsを入れたときのRubyと、今使っているRubyのバージョンが違うと起きることがある、と書かれています。Rubyを入れ替えたあとなら、今のRubyで、CocoaPodsを入れ直してみてください。
古いとき
Flutterのソースコードでは、CocoaPodsは1.10.0以上が要り、1.16.2以上がおすすめとされています。1.10.0より古いと pod install を飛ばし、1.16.2より古いと警告を出したうえで進みます。
Xcodeの新しいプロジェクトの形(ファイルを同期するフォルダ)に、古いCocoaPodsが対応していないときは、次の案内が出ます。
Error: Your Cocoapods might be out-of-date and unable to support synchronized groups/folders. Please update to a minimum version of 1.16.2 and try again.CocoaPodsの公式のガイドでは、上げるときは、もう一度 gem install するだけです。最初に sudo を付けて入れたなら、上げるときも sudo を付けます。
参考:Set up iOS development(Flutter docs、2026年11月12日確認)/Getting Started(CocoaPods Guides、2026年11月12日確認)/cocoapods.dart(Flutterのソースコード、2026年11月12日確認)
4. specs(パッケージの一覧)が古いとき
CocoaPodsは、どのパッケージのどのバージョンがあるかを、specs(スペック)という一覧で調べます。手元の一覧が古いと、パッケージが求める新しいバージョンが見つからず、Flutterは次の案内を出します。
Error: CocoaPods's specs repository is too out-of-date to satisfy dependencies.
To update the CocoaPods specs, run:
pod repo update案内のとおり、一覧を新しくしてから、もう一度ビルドします。
pod repo update参考:cocoapods.dart(Flutterのソースコード、2026年11月12日確認)
5. iOSの最小バージョンが足りないとき
パッケージを足したとたんに、次のような案内が出ることがあります("..." の所には、パッケージの名前が入ります)。
Error: The plugin "..." requires a higher minimum iOS deployment version than your application is targeting.「このパッケージは、アプリが対応しているより新しいiOSを求めている」という意味です。Flutterが必要なバージョンを読み取れたときは、続けて「少なくとも〇〇まで上げてください」と、数字も出してくれます。
直すのは、アプリが対応する一番古いiOSのバージョン(iOS Deployment Target)です。 Flutterの公式ドキュメントでは、Flutterが対応するのはiOS 13以降で、アプリやパッケージがそれより新しいiOSの機能を使うなら、求められる一番高いバージョンに上げる、とされています。
直し方
- Flutterのプロジェクトのフォルダで、
open ios/Runner.xcworkspaceを打ってXcodeを開く - 左の一覧で「Runner」のターゲットを選ぶ
- 「Build Settings」のタブの「Deployment」の所にある「iOS Deployment Target」を、エラーに出た数字にする
ios/Podfileの頭の方にあるplatform :ios, '…'の行も、同じ数字にそろえる- もう一度ビルドする
4の行は、Flutterが作るPodfileでは、最初は行の頭に # が付いていて、コメントになっています。CocoaPodsの公式の説明では、この platform の行は、どのiOS向けに組み立てるかを決めるものです。# を外して、Xcodeの側と同じ数字にしておくと、2か所の食い違いがなくなります。
platform :ios, '15.0'(上の 15.0 は形の例です。エラーに出た数字にしてください)
数字を上げると、それより古いiOSの端末には、アプリを入れられなくなります。 iOS Deployment Targetは、アプリが対応する一番古いiOSのバージョンだからです。上げる前に、そのパッケージが本当に要るのかも、一度考えてみてください。
パッケージの「中の部品」が原因のとき
案内の文が、次のように「プラグインが使っている別のpod」の話になっていることもあります。
Error: The pod "..." required by the plugin "..." requires a higher minimum iOS deployment version than the plugin's reported minimum version.この場合は、アプリの数字を上げても直らないことがあります。Flutterの案内では、そのプラグインを外すか、プラグインの開発者に相談するように、とされています。
参考:Build and release an iOS app(Flutter docs、2026年11月12日確認)/Podfile Syntax Reference(CocoaPods Guides、2026年11月12日確認)/cocoapods.dart・Podfile-ios(Flutterのソースコード、2026年11月12日確認)
6. AppleシリコンのMacで止まるとき
AppleシリコンのMacでは、CocoaPodsが使っているffi(RubyからCの部品を呼ぶための部品)が、Intelのチップ向けのもののままになっていて、pod install が失敗することがあります。Flutterは、出力の中に、ffiのIntel向けの部品に関するエラーを見つけると、次の案内を出します。
Error: To set up CocoaPods for ARM macOS, run:
sudo gem uninstall ffi && sudo gem install ffi -- --enable-libffi-alloc案内のとおり、ffiをいったん消して、入れ直します。そのあと、もう一度ビルドしてください。
このサイトでは、2021年に、AppleシリコンのMacで pod install が「Illegal instruction at・・」で止まったときの直し方を書いています。そのときは、ターミナルをRosetta(Intel向けのアプリを動かす仕組み)で開く方法を使っていました。今のFlutterの案内は、Rosettaを通さずに、AppleシリコンのままでffiとCocoaPodsを使う形です。 2021年の記事は、当時の環境での直し方として読んでください。
参考:cocoapods.dart(Flutterのソースコード、2026年11月12日確認)
7. Swift Package Managerとの食い違い・Podfileが古いとき
CocoaPodsとSwiftPMのパッケージが食い違うとき
1の節のとおり、今のFlutterでは、SwiftPMに対応したパッケージと、CocoaPodsで組み込まれるパッケージが、1つのアプリに混ざることがあります。そのとき、CocoaPodsで組み込まれるパッケージが、SwiftPMで組み込まれる別のパッケージに頼っていると、次のエラーになります。
Error: A dependency conflict has occurred because ... uses CocoaPods while ... uses Swift Package Manager.Flutterの案内では、CocoaPodsを使っている側のパッケージの開発者に、SwiftPMへの対応をお願いするように、とされています。自分でできることとしては、そのパッケージの新しいバージョンで対応していないかを、pub.devのページや変更履歴(CHANGELOG)で確かめるのが先です。
Podfileの書き方が古いとき
Flutterのバージョンを大きく上げたあとに、次の警告が出ることがあります。
Warning: Podfile is out of dateFlutterのソースコードでは、Podfileに古い書き方が残っているときに出る警告で、iOSではここでビルドが止まります。案内されている直し方は、Podfileを消して、Flutterに作り直してもらう方法です。
rm ios/Podfile消したあとに、もう一度ビルドすると、今のFlutterの形でPodfileが作られます。Podfileを自分で書き足していたなら、消す前に中身を控えておいてください。 作り直したPodfileには、書き足した所は残りません。
CocoaPodsを使わなくなったら
使っているパッケージが全部SwiftPMに対応したら、CocoaPodsをプロジェクトから外すこともできます。手順は、Flutterの公式ドキュメントの「Swift Package Manager for app developers」に載っています(pod deintegrate を打ってから、ios/Podfile・ios/Podfile.lock・ios/Pods/ などを消す流れです)。
公式ドキュメントでは、どれか1つでもSwiftPMに対応していないパッケージがあると、FlutterはCocoaPodsに戻るので、外す前に全部のパッケージが対応しているかを確かめるように、とされています。
参考:Swift Package Manager for app developers(Flutter docs、2026年11月12日確認)/cocoapods.dart(Flutterのソースコード、2026年11月12日確認)
8. 「Error running pod install」だけで止まるとき
pod install が失敗すると、Flutterは Error running pod install と出して止まります。2の節の表の案内は、Flutterが原因の見当をつけられたときに、あわせて出るものです。
案内が何も付いていないときは、CocoaPods自身が出しているエラーの行を読みます。 CocoaPodsのエラーの中身は、2021年の記事に出てくる [!] Invalid Podfile file のように、[!] で始まる行に書かれていることがよくあります。
それでも見当がつかないときは、前のビルドの残りを片付けてから、もう一度試します。
flutter cleanflutter pub get- もう一度ビルドする
Podfile.lock を消して pod install をやり直す流れは、2021年にこのサイトの記事で書いています。Invalid Podfile file のエラーが出たときに、Podfileを作り直す話も入っています。
直すときに気をつけたいこと
- Flutterの案内の文を、まず読む
長い出力の中から、2の節の表の文を探します。原因の種類がわかれば、余計なものを消したり入れ直したりせずに済みます。
- 1回に変えるのは1か所だけ
CocoaPodsの入れ直し、iOSの最小バージョン、パッケージの更新を一度にやると、次に出たエラーがどれのせいかわからなくなります。
- Podfileは、消す前に中身を控える
作り直すと、自分で書き足した所は消えます。Gitで管理しているなら、消す前にコミットしておくと戻せます。
「どれを触ったら、ええねん!?」と迷うときほど、1つ変えて、ビルドして、確かめる、を繰り返すのが近道です。
(AndroidのビルドがGradleのエラーで止まったときの直し方は、こちらの記事にまとめています)
iOSのビルドで手が止まっている方へ
CocoaPodsの案内の文が見つかっても、Rubyの入れ直し、Xcodeの設定、Podfileの作り直しと、iOSのビルドは触る所が多いので、どこまで手を入れていいのかを、ひとりで見極めるのは意外と難しいですよね。
ぼくのFlutterビルドエラー解決(Zoom・60分)では、CocoaPodsやパッケージの依存関係のエラーも対象にしていて、Zoomの画面共有で、エラーが出る様子を一緒に確かめながら、解決を目指します。直し方の説明に加えて、同じエラーで止まらないためのアドバイスもお伝えします。よろしければ、お気軽にご相談ください。
まとめ
参考:Set up iOS development・Swift Package Manager for app developers・Build and release an iOS app(いずれもFlutter docs、2026年11月12日確認)/cocoapods.dart・Podfile-ios(Flutterのソースコード、2026年11月12日確認)/Getting Started・Podfile Syntax Reference(CocoaPods Guides、2026年11月12日確認)/CocoaPods Specs Repo(CocoaPods Blog、2026年11月12日確認)
何かのお役に立てれば幸いです。
- FlutterのCocoaPodsのエラーは、ログの中にFlutterが出す「Error:」「Warning:」の行で、原因の種類を見分ける
- 2026年のFlutterは、Flutter 3.44からSwift Package Managerが最初から有効。SwiftPMに対応していないパッケージだけが、CocoaPodsで組み込まれる
- CocoaPodsのレジストリは、2026年12月2日に読み取り専用になる。今あるビルドは動き続けるが、CocoaPods経由の更新は届かなくなる
- 「CocoaPods not installed」「broken」は、CocoaPodsを入れる・入れ直す。公式のガイドは、システムのRubyを使わない方法をすすめている。Flutterのおすすめは1.16.2以上
- 「specs repository is too out-of-date」は、
pod repo update - 「requires a higher minimum iOS deployment version」は、XcodeのRunnerの「iOS Deployment Target」と、Podfileの
platform :iosの行を、エラーに出た数字にそろえる。上げると古いiOSの端末には入れられなくなる - AppleシリコンのMacの「To set up CocoaPods for ARM macOS」は、案内のとおりffiを入れ直す。2021年のRosettaを使う方法は、当時の直し方
- 「dependency conflict」は、CocoaPods側のパッケージの新しい版がSwiftPMに対応していないかを確かめる
- 「Podfile is out of date」は、中身を控えてから
ios/Podfileを消し、Flutterに作り直してもらう - 案内が付かない「Error running pod install」は、
[!]で始まるCocoaPodsの行を読み、flutter cleanとflutter pub getで片付けてからやり直す
ビルドエラー解決・動作確認・申請代行まで、現役開発者が対応します。










