Flutter iOS 빌드 CocoaPods not installed 해결법

서론

Flutter로 iOS 빌드를 하다 보면 아래와 같은 메시지와 함께 빌드가 멈추는 경우가 많습니다.

• CocoaPods not installed or not in valid state.
• Error: CocoaPods not installed. Skipping pod install.
• pod: command not found

CocoaPods는 iOS 네이티브 의존성(Flutter 플러그인의 iOS 구현 포함)을 내려받고 Xcode 프로젝트에 연결하는 역할을 합니다. 따라서 Flutter iOS 빌드에서 CocoaPods 관련 오류는 “설치가 안 됨”뿐 아니라 “설치돼 있는데 Flutter가 못 찾음”, “pod install이 깨짐”, “권한/아키텍처 문제”처럼 다양한 원인으로 발생합니다.

이 글은 원인을 빠르게 분리하고, 로컬 개발 환경과 CI(예: GitHub Actions, Codemagic, Jenkins)에서 재발 방지까지 포함해 정리합니다. 장애 원인을 빠르게 좁히는 접근은 인프라 트러블슈팅과 크게 다르지 않습니다. 로그를 기반으로 원인을 분기하는 방식이 익숙하다면 K8s CrashLoopBackOff 원인 10분내 찾는 법 같은 글의 사고방식이 iOS 빌드에도 그대로 통합니다.

1) 먼저 확인: Flutter가 요구하는 기본 전제

Xcode/Command Line Tools 설치 여부

CocoaPods는 Ruby 기반이지만, 실제로는 Xcode 툴체인과 함께 움직입니다.

xcodebuild -version
xcode-select -p

• xcode-select -p가 비어 있거나 에러면 Command Line Tools가 없을 수 있습니다.

xcode-select --install

Flutter doctor로 단서 얻기

flutter doctor -v

여기서 iOS toolchain 섹션에 CocoaPods 관련 경고가 뜨는지 확인합니다. 경고 문구가 동일해 보여도 실제 원인은 다를 수 있으니, 아래 체크리스트로 분기합니다.

2) 가장 흔한 원인: CocoaPods 미설치 또는 PATH 문제

pod 명령이 실제로 있는지

which pod
pod --version

• which pod가 아무것도 출력하지 않으면 PATH 문제거나 미설치입니다.
• pod --version에서 Ruby 관련 에러가 터지면 Ruby 환경/권한 문제일 가능성이 큽니다.

3) 권장 설치 방식: Homebrew로 CocoaPods 설치

macOS 개발 환경에서는 Homebrew 설치가 가장 간단하고 재현성이 좋습니다.

brew update
brew install cocoapods
pod --version

이미 설치돼 있다면 업데이트:

brew upgrade cocoapods

설치 후 Flutter 프로젝트에서 iOS 의존성을 다시 설치합니다.

flutter clean
rm -rf ios/Pods ios/Podfile.lock
flutter pub get
cd ios
pod install
cd ..
flutter build ios

왜 brew가 안전한가?

• 시스템 Ruby(/usr/bin/ruby)에 gem을 깔 때 발생하는 권한 문제를 피할 수 있습니다.
• Apple Silicon/Intel 환경에서 비교적 안정적으로 동작합니다.

4) gem 설치를 쓰는 경우(권한/시스템 Ruby 이슈 포함)

회사 정책이나 CI 이미지 구성 때문에 gem install cocoapods를 써야 할 때가 있습니다. 이 경우 아래 문제가 자주 납니다.

• You don't have write permissions for the /Library/Ruby/Gems/... directory.
• pod: command not found (설치는 됐는데 PATH에 없음)

(비권장) sudo gem install

sudo gem install cocoapods
pod --version

동작은 하지만, 시스템 영역에 설치되어 환경 오염/권한 꼬임이 생길 수 있어 권장하지 않습니다.

(권장) rbenv로 Ruby 버전 분리

Ruby를 프로젝트/사용자 영역으로 분리하면 권한 이슈가 크게 줄어듭니다.

brew install rbenv ruby-build
rbenv init

쉘 설정에 초기화 추가(zsh 기준):

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

Ruby 설치 후 CocoaPods 설치:

rbenv install 3.2.2
rbenv global 3.2.2
ruby -v

gem install cocoapods
rbenv rehash
pod --version

이후 pod install을 다시 수행합니다.

5) Apple Silicon(M1/M2/M3)에서의 함정: 아키텍처/로제타

Apple Silicon에서 과거 문서대로 따라 하다 보면 Intel(x86_64)용 Ruby/gem이 섞이거나, 반대로 arm64 환경에서 일부 네이티브 확장이 꼬이는 경우가 있습니다.

현재 터미널 아키텍처 확인

uname -m

• arm64면 Apple Silicon 네이티브
• x86_64면 Rosetta로 실행 중

가능하면 한쪽으로 통일하세요. 특히 CI/빌드 머신에서 터미널이 Rosetta로 열려 있으면 pod 바이너리/젬 경로가 섞여 “설치됐는데 못 찾는” 현상이 발생합니다.

Rosetta가 필요한 경우

일부 레거시 조합에서 Rosetta가 필요할 수 있습니다.

softwareupdate --install-rosetta --agree-to-license
arch -x86_64 pod --version
arch -x86_64 pod install

단, 이 경우 Flutter/Xcode 빌드도 동일한 아키텍처 관점에서 일관되게 맞춰야 합니다.

6) CocoaPods는 있는데 “유효하지 않은 상태”로 뜰 때

Flutter가 종종 이렇게 말합니다.

• CocoaPods not installed or not in valid state.

이는 단순 미설치가 아니라 pod repo, 캐시, 혹은 설치 상태가 깨진 경우가 많습니다.

CocoaPods repo 업데이트/재설치

pod repo update
pod setup

캐시/Pods 정리 후 재설치

cd ios
rm -rf Pods Podfile.lock
pod deintegrate
pod install --repo-update
cd ..

Podfile이 최소 요건을 충족하는지

ios/Podfile에 플랫폼 버전이 너무 낮거나, 프로젝트 설정과 충돌하면 설치가 실패하고 Flutter에서 CocoaPods 문제로 뭉뚱그려 보일 수 있습니다.

예시(일반적인 Flutter 기본 형태):

platform :ios, '12.0'

# CocoaPods analytics sends network stats synchronously affecting flutter build latency.
ENV['COCOAPODS_DISABLE_STATS'] = 'true'

project 'Runner', {
  'Debug' => :debug,
  'Profile' => :release,
  'Release' => :release,
}

flutter_ios_podfile_setup

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
  end
end

플러그인에 따라 use_frameworks!/use_modular_headers! 조합이 충돌을 일으키는 경우도 있으니, pod install 로그를 반드시 확인하세요.

7) Flutter 명령으로 자동 복구 시도(빠른 루틴)

대부분의 로컬 환경에서는 아래 루틴으로 해결됩니다.

flutter clean
flutter pub get
cd ios
pod install --repo-update
cd ..
flutter run

여기서도 실패한다면, “CocoaPods 미설치”가 아니라 “pod install이 실패”하는 상황일 확률이 높습니다. 이때는 pod install의 에러 본문이 핵심이며, Flutter 출력은 요약만 보여주기도 합니다.

8) CI 환경에서 자주 터지는 패턴과 해결

CI에서 흔한 실패 형태:

• 캐시된 Pods/ 또는 Podfile.lock가 깨진 채로 재사용됨
• CocoaPods 버전이 로컬과 달라 lock 해석이 달라짐
• Ruby 버전이 바뀌어 gem이 로드되지 않음

CI에서의 권장 전략

1. CocoaPods 버전을 고정(재현성)
2. pod install은 항상 깨끗한 상태에서 수행하거나, 캐시 키를 엄격히
3. Xcode 버전과 함께 관리

예: GitHub Actions에서 brew로 설치하는 스텝(개념 예시)

- name: Install CocoaPods
  run: |
    brew update
    brew install cocoapods
    pod --version

- name: Install iOS pods
  run: |
    flutter pub get
    cd ios
    pod install --repo-update

캐시를 쓴다면 Podfile.lock과 CocoaPods 버전을 캐시 키에 포함하세요. 캐시가 “성공을 가속”하기도 하지만 “실패를 영구화”하기도 합니다. 이런 류의 진단은 네트워크/엣지 장애를 로그로 좁히는 방식과 비슷한데, 접근법이 궁금하면 Cloudflare 520·521, Nginx·ALB 로그로 30분 진단처럼 로그 기반 분해 과정을 참고해도 좋습니다.

9) 그래도 안 되면: 체크리스트(원인별 빠른 분기)

A. pod: command not found

• which pod 결과 없음 → PATH 또는 설치 자체 문제
• brew 설치 후에도 없음 → 쉘 초기화 파일(~/.zshrc)에서 brew path가 누락됐을 수 있음

# Apple Silicon 기본 brew 경로
export PATH="/opt/homebrew/bin:$PATH"
source ~/.zshrc
which pod

B. 권한 에러(/Library/Ruby/Gems)

• 시스템 Ruby에 gem 설치 시도 중
• 해결: brew cocoapods 또는 rbenv 사용

C. pod install 자체가 실패

• Flutter 메시지는 CocoaPods 문제처럼 보이지만, 실제는 특정 Pod 의존성 충돌
• 해결: cd ios && pod install --repo-update 로그를 끝까지 확인

D. Xcode 프로젝트/워크스페이스 혼동

CocoaPods를 쓰면 빌드는 .xcworkspace를 기준으로 해야 합니다.

• Xcode로 열 때: ios/Runner.xcworkspace
• Runner.xcodeproj로 열면 Pods가 적용되지 않아 빌드가 깨질 수 있습니다.

10) 결론: 가장 재현성 높은 해결 루틴

정리하면, Flutter iOS 빌드의 CocoaPods not installed는 “진짜 미설치”보다 “환경 불일치/깨진 상태”인 경우가 더 많습니다. 다음 루틴을 먼저 적용하세요.

1. Xcode/CLT 확인: xcode-select -p
2. CocoaPods 설치(권장: brew): brew install cocoapods
3. iOS 폴더 정리 후 재설치:

flutter clean
rm -rf ios/Pods ios/Podfile.lock
flutter pub get
cd ios
pod install --repo-update
cd ..

4. Apple Silicon이면 아키텍처 일관성 확인: uname -m
5. CI는 CocoaPods 버전/캐시 키를 고정

이 과정을 거치면 대부분의 “CocoaPods not installed” 계열 이슈는 해결되며, 남는 케이스는 pod install의 실제 에러(의존성 충돌/플러그인 문제/최소 iOS 버전 문제)로 좁혀집니다.