beautifulsoups.dev
Published on

Flutter iOS 빌드 CocoaPods not installed 해결

Authors

Flutter로 iOS 빌드를 하다 보면 가장 흔하게 마주치는 에러 중 하나가 CocoaPods not installed 입니다. 메시지는 단순하지만, 실제 원인은 여러 갈래로 나뉩니다. 예를 들어 CocoaPods가 정말로 설치되어 있지 않은 경우도 있지만, 설치는 되어 있는데 PATH 문제로 pod 바이너리를 못 찾거나, Apple Silicon에서 아키텍처가 꼬이거나, Ruby 환경이 충돌해서 실행이 실패하는 경우도 많습니다.

이 글에서는 Flutter가 iOS 의존성 관리를 위해 CocoaPods를 어떻게 사용하는지부터, macOS 환경별로 가장 안전한 설치 방법, 그리고 이미 설치했는데도 계속 같은 오류가 나는 상황을 단계적으로 진단하는 방법까지 정리합니다.

관련해서 Podfile.lock 충돌로 iOS 빌드가 깨지는 케이스는 별도 글로 정리해 두었습니다. 상황이 비슷하게 겹칠 수 있으니 함께 참고하면 좋습니다: Flutter iOS 빌드 실패 - Podfile.lock 충돌 해결 가이드

에러가 의미하는 것: Flutter가 pod 실행에 실패

Flutter iOS 빌드 과정에서 플러그인 네이티브 의존성은 ios/Podfile을 통해 CocoaPods로 설치됩니다. 따라서 Flutter는 내부적으로 다음과 같은 호출을 수행합니다.

  • pod --version 으로 설치 여부 확인
  • pod install 로 ios/Pods 구성
  • Xcode 빌드 시 Pods.xcodeproj 및 .xcworkspace 사용

즉 CocoaPods not installed는 대부분 아래 중 하나입니다.

  1. pod 커맨드 자체가 없음
  2. pod는 있으나 현재 셸에서 찾지 못함(PATH 문제)
  3. pod 실행이 Ruby 문제로 실패(의존 gem 충돌, 권한 문제 등)
  4. Apple Silicon에서 pod가 다른 아키텍처로 설치되어 실행 실패

1단계: 현재 상태를 빠르게 진단하기

터미널에서 아래를 순서대로 확인합니다.

which pod
pod --version
ruby -v
flutter doctor -v
  • which pod가 아무것도 출력하지 않으면: 설치 또는 PATH 문제
  • pod --version에서 에러가 나면: Ruby 환경/권한/아키텍처 문제 가능
  • flutter doctor -v에서 iOS toolchain 섹션에 CocoaPods 경고가 함께 뜨는지 확인

추가로 Homebrew 기반인지 확인하려면:

brew --version
brew list | grep cocoapods

2단계: 가장 권장되는 설치 방법(Homebrew)

macOS에서 Flutter 개발을 한다면, 일반적으로 CocoaPods는 Homebrew로 설치하는 편이 가장 안정적입니다(시스템 Ruby gem 경로 문제를 피하기 쉬움).

brew update
brew install cocoapods
pod --version

설치 후에도 pod를 못 찾는다면, Homebrew 경로가 PATH에 없을 수 있습니다.

Apple Silicon에서 PATH 확인(brew prefix)

Apple Silicon(M1/M2/M3)은 보통 Homebrew가 /opt/homebrew 아래에 설치됩니다.

brew --prefix

/opt/homebrew가 나온다면, 셸 설정에 다음이 들어 있어야 합니다.

  • zsh 기준: ~/.zshrc
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
which pod
pod --version

Intel Mac은 보통 /usr/local 입니다.

3단계: RubyGems로 설치해야 하는 경우(권한 이슈 주의)

회사 정책 또는 환경 제약으로 Homebrew 설치가 어렵다면 RubyGems로 설치할 수도 있습니다.

gem install cocoapods
pod --version

다만 여기서 You don't have write permissions 같은 권한 에러가 나면 sudo gem install cocoapods로 해결하는 경우가 많지만, 시스템 Ruby에 sudo로 gem을 설치하는 방식은 장기적으로 충돌을 만들 수 있습니다.

가능하면 Ruby 버전 매니저를 쓰는 편이 안전합니다.

rbenv를 사용하는 방식(권장)

brew install rbenv ruby-build
rbenv init

이후 셸 설정에 rbenv 초기화를 추가하고 Ruby를 설치합니다.

rbenv install 3.2.2
rbenv global 3.2.2
ruby -v

gem install cocoapods
pod --version

핵심은 pod가 특정 Ruby에 종속되므로, 팀 내에서 Ruby 버전이 섞이면 갑자기 pod가 동작하지 않는 상황이 생길 수 있다는 점입니다. CI나 팀 개발에서는 Ruby 버전까지 고정하는 것이 좋습니다.

4단계: 설치했는데도 Flutter가 계속 CocoaPods not installed라고 하는 경우

이 경우는 대개 pod는 설치되어 있지만 Flutter가 실행되는 환경에서 pod를 찾지 못하는 문제입니다.

(1) Android Studio/VS Code에서 실행한 터미널과 로그인 셸이 다름

IDE 내장 터미널은 로그인 셸 설정을 일부만 가져오는 경우가 있습니다. ~/.zshrc에만 PATH를 넣어 둔 상태라면, GUI 앱에서 실행 시 반영이 안 될 수도 있습니다.

해결 방법:

  • ~/.zprofile에도 Homebrew shellenv를 추가
# ~/.zprofile

if [ -x /opt/homebrew/bin/brew ]; then
  eval "$(/opt/homebrew/bin/brew shellenv)"
fi

적용 후 macOS에서 IDE를 완전히 종료했다가 다시 실행합니다.

(2) pod는 있는데 실행 시 Ruby 오류가 발생

예를 들어 다음과 같은 형태입니다.

  • pod 실행 시 LoadError 또는 cannot load such file 류
  • ffi gem 관련 오류

이럴 때는 CocoaPods를 재설치하거나, Ruby 환경을 정리하는 것이 빠릅니다.

Homebrew로 설치했다면:

brew reinstall cocoapods
pod --version

gem으로 설치했다면:

gem uninstall cocoapods

gem install cocoapods
pod --version

(3) Apple Silicon에서 Rosetta로 설치된 pod와 네이티브가 섞임

가끔 arch -x86_64로 실행한 터미널에서 설치한 gem/바이너리가 남아, ARM 환경에서 실행이 꼬입니다. 다음으로 현재 터미널 아키텍처를 확인합니다.

uname -m
  • arm64가 일반적
  • x86_64라면 Rosetta 터미널일 수 있음

가능하면 ARM 환경에서 Homebrew와 CocoaPods를 통일하세요.

5단계: Flutter iOS 폴더를 깨끗하게 정리하고 Pod 재설치

CocoaPods 설치를 해결했어도, 기존 ios/Pods나 캐시가 꼬여 빌드가 계속 실패할 수 있습니다. 아래 순서가 가장 재현성이 좋습니다.

flutter clean
rm -rf ios/Pods ios/Podfile.lock
rm -rf ~/Library/Caches/CocoaPods
rm -rf ~/.cocoapods

flutter pub get
cd ios
pod repo update
pod install
cd ..

flutter build ios

팀 프로젝트라면 Podfile.lock을 무조건 지우는 것이 정답은 아닙니다. 하지만 CocoaPods not installed를 해결하는 과정에서 환경이 크게 바뀌었다면, 일단 로컬에서만 재생성해 상태를 정상화한 뒤, lockfile은 팀 정책에 맞춰 커밋 여부를 판단하는 편이 좋습니다.

6단계: Xcode 설정과 라이선스도 함께 확인

가끔 CocoaPods 문제처럼 보이지만, 실제로는 Xcode CLI 설정이 깨져 iOS toolchain 진단이 실패하는 경우가 있습니다.

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
xcodebuild -version

그 다음 다시:

flutter doctor -v

7단계: CI 환경에서의 체크리스트

CI에서 특히 많이 터지는 포인트만 압축하면 다음과 같습니다.

  • CocoaPods 설치 단계 명시(brew install cocoapods 또는 gem install cocoapods)
  • Ruby 버전 고정(rbenv, ruby/setup-ruby 등)
  • pod repo update는 시간이 오래 걸리므로 캐시 전략 고려
  • cd ios && pod install을 빌드 파이프라인에 포함

예시 스크립트:

set -e

flutter --version
flutter doctor -v

brew update
brew install cocoapods
pod --version

flutter pub get
cd ios
pod install
cd ..

flutter build ios --release

자주 묻는 질문

sudo gem install cocoapods로 해결해도 되나요

급한 불은 끌 수 있지만, 시스템 Ruby에 sudo로 gem을 설치하면 macOS 업데이트나 Ruby 경로 변경 시 재현 어려운 문제가 생길 수 있습니다. 가능하면 Homebrew 또는 rbenv 같은 버전 매니저 기반으로 통일하는 것을 권합니다.

pod install은 되는데 Flutter가 계속 CocoaPods 미설치라고 합니다

대부분 Flutter를 실행하는 셸과 pod가 설치된 셸의 환경이 다릅니다. which pod 결과가 Flutter 실행 환경에서도 동일한지 확인하고, 필요하면 ~/.zprofile에 PATH 초기화를 추가한 뒤 IDE를 재시작하세요.

마무리

CocoaPods not installed는 단순히 설치 유무 문제처럼 보이지만, 실제로는 PATH, Ruby 관리 방식, Apple Silicon 아키텍처, IDE 실행 환경 차이까지 함께 얽혀 발생합니다.

  • 우선 which pod와 pod --version으로 “찾는 문제”인지 “실행 문제”인지 분리
  • 가능하면 Homebrew로 설치하고 PATH를 로그인 셸까지 반영
  • 꼬인 iOS 폴더는 flutter clean과 함께 Pods/캐시를 정리한 뒤 pod install로 재구성

여기까지 진행하면 대부분의 Flutter iOS 빌드 환경에서 CocoaPods 관련 오류를 안정적으로 해결할 수 있습니다.

Discuss on Twitter • View on GitHub