CocoaPods Is Going Read-Only: Migrating a 20+ Dependency iOS App to Swift Package Manager

Your Podfile still installs. That is exactly why this is easy to postpone — and why a project with twenty-plus dependencies should start now rather than in December.

First, what actually changes

CocoaPods trunk is moving to a read-only state. In the official words:

"December 2nd 2026 — I will switch trunk to not accept new Podspecs permanently."

And from Firebase:

"Firebase 12 is the final major version published to CocoaPods, and Firebase will stop publishing new versions to CocoaPods in October 2026."

Read-only is not shut down. Existing pod versions stay downloadable, the Specs repo and CDN keep serving, and pod install keeps resolving what it resolves today. CocoaPods is explicit about this: "Making the switch will not break builds for people using CocoaPods in 2026 onwards." Firebase says the same about its own packages: existing versions "in CocoaPods will remain installable and functional as long as CocoaPods ecosystem support continues."

What you lose after December is the ability to receive new versions through trunk. For an app that ships quarterly, that is a slow, undramatic problem — the worst kind, because nothing pages you at 3 a.m.

Timeline

When	What happens
2024-11-30	CocoaPods announces the plan: "In two years we plan to turn CocoaPods trunk to be read-only."
Mid–late 2025	First email to everyone who contributed a Podspec
Sep–Oct 2026	Second email, roughly one month before the test run
Oct 2026	Firebase stops publishing to CocoaPods; Firebase 12 is the last major version
Nov 1–7, 2026	Test run of read-only, "giving automation a chance to break early"
Dec 2, 2026	Trunk permanently stops accepting new Podspecs
After	Existing versions remain installable; Specs repo and CDN keep serving

CocoaPods adds a caveat worth quoting: "These dates are not set in stone." Treat the December date as a planning deadline, not a hard API cutoff. Flutter has already moved in the same direction — starting with Flutter 3.44, Swift Package Manager replaces CocoaPods as the default for iOS and macOS apps — so the direction of travel is not in question.

Step 1: Inventory and freeze

Do this on a branch, and commit the current working state before you touch anything.

cd "$(git rev-parse --show-toplevel)"
git checkout -b spm-migration

grep -nE "^\s*pod " Podfile | tee /tmp/pods.txt
wc -l < /tmp/pods.txt

git add Podfile Podfile.lock
git commit -m "chore: snapshot CocoaPods state before SPM migration"

Then go through /tmp/pods.txt line by line and mark each dependency: has a Swift package, has a binary xcframework, or has neither. The third bucket decides your schedule. Twenty pods where eighteen migrate cleanly is a week; three pods with no package support can eat a month.

One thing people miss: CocoaPods subspecs do not map one-to-one onto Swift packages. A pod like Vendor/Core and Vendor/UI may become two products of a single package, or one product with everything included. Read the vendor's own SPM instructions.

Step 2: Deintegrate

Quit Xcode first. pod deintegrate rewrites the project file, and an open Xcode window will happily overwrite those changes when it saves.

pod deintegrate
pod clean

mkdir -p archive/cocoapods
git mv Podfile archive/cocoapods/Podfile
git mv Podfile.lock archive/cocoapods/Podfile.lock

rm -rf Pods *.xcworkspace
git status --short

Archive, do not delete. The Podfile.lock is your rollback artifact for the rest of the migration.

Step 3: Add the packages

For an app target, the path of least resistance is Xcode: open the .xcodeproj, choose File → Add Package Dependencies, paste the repository URL, pick the products, and confirm they are added to the target's "Frameworks, Libraries, and Embedded Content."

If your app is split into local Swift packages, declare the dependency in Package.swift instead:

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "AppCore",
    platforms: [.iOS(.v17)],
    dependencies: [
        .package(
            url: "https://github.com/firebase/firebase-ios-sdk",
            from: "12.0.0"
        )
    ],
    targets: [
        .target(
            name: "AppCore",
            dependencies: [
                .product(name: "FirebaseAuth", package: "firebase-ios-sdk"),
                .product(name: "FirebaseFirestore", package: "firebase-ios-sdk")
            ]
        )
    ]
)

Commit Package.resolved alongside Package.swift. It is the SPM equivalent of Podfile.lock, and without it your CI and your laptop can resolve different revisions of the same branch-based dependency.

Step 4: Clean the leftovers

CocoaPods leaves more behind than the Pods/ directory. Check for:

grep -n "PODS_ROOT\|Pods/" App.xcodeproj/project.pbxproj

You are looking for build settings pointing at ${PODS_ROOT}, and build phases named [CP] Check Pods Manifest.lock, [CP] Embed Pods Frameworks, and [CP] Copy Pods Resources. Remove them.

Keep the Crashlytics dSYM upload run script, but note that Firebase documents a different script path for SPM checkouts than for CocoaPods installs. Copy the current version from the Crashlytics setup page rather than editing the old path by hand. A stale path here fails silently: uploads just stop, and you find out weeks later when a crash report has no symbols.

Step 5: CI

The failure mode in CI is almost always cache, not code. Old caches still contain a Pods/ directory and a stale workspace that no longer exists in the repo.

- name: Resolve packages
  run: |
    rm -rf ~/Library/Caches/CocoaPods
    rm -rf ~/Library/Caches/org.swift.swiftpm
    xcodebuild -resolvePackageDependencies \
      -project App.xcodeproj \
      -scheme App \
      -clonedSourcePackagesDirPath "$PWD/.spm-cache"

- name: Build
  run: |
    xcodebuild -project App.xcodeproj \
      -scheme App \
      -destination 'generic/platform=iOS' \
      -clonedSourcePackagesDirPath "$PWD/.spm-cache" \
      -onlyUsePackageVersionsFromResolvedFile \
      build

Cache .spm-cache with the hash of Package.resolved as the key, and drop any cache keyed on Podfile.lock. -onlyUsePackageVersionsFromResolvedFile makes CI fail loudly on a resolution mismatch instead of quietly pulling something newer.

Step 6: Verify, then keep the exit open

Run a clean build from an empty derived data directory, then exercise the paths that dependency managers actually break: login, a database read, push registration, a crash upload, and one analytics event. Those five cover most of what a migration silently damages.

Rollback stays cheap for as long as you keep the branch: git revert the migration commit, restore archive/cocoapods/, and pod install. Once you delete that archive, rollback becomes a rewrite.

Three pitfalls that cost real time

Private pods. A private pod becomes a Swift package hosted in a private Git repository. Xcode will prompt for credentials locally; CI needs an SSH key or a token wired into git. If the private pod ships as a prebuilt binary, it cannot become a normal package — it becomes a .binaryTarget, and the artifact must be an xcframework.

Binary dependencies. For a local artifact:

.binaryTarget(name: "VendorSDK", path: "Vendor/VendorSDK.xcframework")

For a remote one you need both url and checksum, and the checksum must be recomputed every time the artifact changes. Plain .framework files and static .a libraries are not accepted; they have to be repackaged as an xcframework first.

Resource bundles. CocoaPods resource_bundles become SPM resources on the target:

.target(
    name: "DesignSystem",
    resources: [.process("Resources")]
)

Use .process for images and asset catalogs so they get optimized, .copy for directories whose structure must be preserved. Access them with Bundle.module — and remember that Bundle.module only exists inside the package that declares the resources. If the app needs to reach them, expose a small accessor from the package instead of referring to Bundle.module from app code, which will not compile.

One judgment

This is a registry freeze, not a shutdown: nothing you shipped breaks on December 2. But a twenty-dependency migration is a multi-week job with a binary-artifact worst case, and the November test run is when other people's automation finds its bugs. If CocoaPods is still in your Podfile, put the branch on the calendar this month.

---

More iOS migration write-ups and project notes: https://hhfa008.github.io/personal/cases.html