How to migrate from CocoaPods to SwiftPM safely

Before you begin

• The distribution requires Apple Silicon and has macOS 14 as its installation minimum.
• 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.

PkgLift 1.0.1 fails closed on unsupported .xcproj definitions before analysis or migration, including bundles with both PBX and JSON definitions. This maintenance boundary does not add JSON-project migration; the stable 1.x CLI, JSON, and Swift library contracts remain unchanged.

The signed CLI runtime was verified on macOS 14.8.9 without an Xcode consumer build. Hosted consumer acceptance used macOS 15.7.9/Xcode 16.4, while separate local validation used macOS 27.0/Xcode 27.0. Check the exact environment matrix; these independent observations do not prove every macOS patch or a continuous range of Xcode versions.

1. Install 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.

PkgLift 1.0.1 was published on 2026-10-02 Europe/Stockholm. Read the release notes and qualification record. To update an existing Homebrew installation, run brew update && brew upgrade pkglift.

After upgrading to 1.0.1, regenerate saved migration plans before dry run or apply: executable plans are bound to their exact producer version. Review the new plan instead of editing its version or evidence fields.

2. Run your first analysis

Open Terminal in your project's folder, or replace the example path below with your repository's location:

cd /path/to/your/repository

The command prints its findings in Terminal. It does not modify your Xcode project or Podfile, and it does not create a migration plan. You can stop here and review the results before continuing.

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

Discovery and explicit selection are available for projects and workspaces, but positive external multi-target/workspace migration qualification remains deferred. Treat those shapes as review boundaries rather than evidence of automatic migration support.

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.

Generate and review a fresh plan after upgrading PkgLift. Plans created by another PkgLift version cannot be applied.

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.

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

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

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