How to migrate from CocoaPods to SwiftPM safely

What PkgLift automates: discovery, classification, planning, typed Xcode project changes, and verification for entries with complete evidence. It deliberately leaves uncertain dependencies under CocoaPods.

Before you begin

Use an Apple Silicon Mac running macOS 14 or later.
Start from a native Xcode repository with a valid baseline build.
Check the compatibility matrix, especially for Objective-C, mixed-language, Carthage, or cross-platform projects.
Commit or stash every existing change. PkgLift refuses to apply a migration to a dirty Git worktree.
Know the shared Xcode scheme used by your normal build or CI.

1. Install PkgLift

brew install Alexsvensson99/tap/pkglift

pkglift version
pkglift registry validate

The release binary is Developer ID-signed and Apple-notarized. The registry validation confirms that the bundled exact mappings can be loaded.

2. Analyze without changing the project

cd /path/to/your/repository
pkglift analyze

PkgLift recursively discovers supported Xcode projects and workspaces beneath the selected root while excluding generated dependency and build trees.

For reviewable output that can move between machines, use pkglift analyze --portable-json. It sanitizes local paths and URL credentials, but can still contain dependency and target names; inspect it before sharing.

When several candidates exist, choose explicitly instead of letting any tool guess:

pkglift analyze --path . \
  --workspace Workspaces/Products.xcworkspace \
  --project Projects/App.xcodeproj

3. Generate and review the plan

pkglift plan

The command writes .pkglift/plan.json. Open it and inspect every direct dependency, destination target, package URL, product, and version requirement.

pkglift plan --portable-json prints a sanitized copy while preserving the complete executable plan in .pkglift/plan.json. Portable output is not a privacy-minimized diagnostics report.

Classification	Your action
AUTO	Verify the exact mapping and target. This is the only class that apply may execute.
REVIEW	Investigate project-specific context or perform the migration manually.
BLOCKED	Resolve the incompatible construct before considering automation.
UNKNOWN	Keep the pod or contribute a verified mapping with official upstream evidence.

Keep the worktree clean. The generated plan itself can appear as an untracked file. For a one-off local test, exclude only .pkglift/plan.json through .git/info/exclude; do not weaken the clean-worktree safeguard.

4. Run the migration preview

pkglift migrate
git status --short
git diff --check

Without --apply, the command is a dry run. The project and index should remain unchanged. Stop if the preview does not match the reviewed plan.

5. Apply only the reviewed automatic entries

pkglift migrate --apply

PkgLift removes only exact migrated pod declarations and adds typed package/product/target linkage. It preserves unrelated Ruby and the CocoaPods integration needed by dependencies that remain.

PkgLift does not run CocoaPods for you. Refresh the remaining pods explicitly:

pod install --clean-install

6. Verify structure, resolution, and build

pkglift verify
pkglift verify \
  --build \
  --scheme MyApp \
  --configuration Debug \
  --destination 'generic/platform=iOS Simulator'

Build verification uses the explicit scheme during both SwiftPM package resolution and the final Xcode build. Configuration, destination, SDK, and derived-data overrides can match your established CI baseline.

7. Review the final diff

Dependency declarations

Confirm that only reviewed pod declarations were removed and every remaining pod is intact.

Xcode project linkage

Confirm the expected package reference, product dependency, and target linkage.

Lockfiles

Confirm the migrated dependency left Podfile.lock and appears in SwiftPM resolution metadata where expected.

Source and resources

PkgLift should not change application source or resource files. Treat any such diff as unexpected.

Share a real-world result

Successful, partial, and intentionally refused migrations all improve the project. Generate a minimized local report, inspect it, and attach only what you are comfortable publishing:

pkglift diagnostics --path . --output pkglift-diagnostics.json

Report a migration result