How to Remove a Pod from an Xcode Project

Why this happens

When you add a dependency via CocoaPods, the tool modifies your workspace configuration, links dynamic frameworks or static libraries in build phases, generates xcconfig files, and records version pins in Podfile.lock.

Developers often try to delete the framework manually from the Pods/ directory or delete files from the Xcode Project Navigator. Doing so breaks your workspace configuration because the generated Pods.xcodeproj and project xcconfig files still expect those targets to exist, resulting in ld: framework not found or missing module build errors.

CocoaPods requires you to manage dependencies through the Podfile manifest. When you edit the manifest and run pod install, CocoaPods reads the delta, purges unreferenced frameworks, regenerates target dependency graphs, and rewrites the xcconfig link flags safely.

How to fix it

1. Delete the pod declaration and run pod install

This is the standard procedure when removing one or more specific pods while keeping CocoaPods active for your other dependencies.

1. Close Xcode to avoid file-lock conflicts.
2. Open your Podfile in a text editor or directly in your terminal:

platform :ios, '16.0'
use_frameworks!

target 'MyApp' do
  # Delete or comment out the line below
  # pod 'Alamofire', '~> 5.8'

  pod 'Kingfisher', '~> 7.0'
end

3. Save the changes to Podfile.
4. Open Terminal, navigate to your project directory containing the Podfile, and run:

pod install

Do not run pod update when simply removing a library. Running pod install inspects the changes between your updated Podfile and the existing Podfile.lock, uninstalls only the unlisted framework, and leaves other resolved dependency versions intact.

5. Verify output in the terminal. CocoaPods will print:

Removing Alamofire
Generating Pods project
Integrating client project
Pod installation complete!

2. Remove obsolete import statements and clean Xcode build cache

After removing the pod at the workspace level, existing source files that reference the deleted module will trigger compiler errors such as No such module 'Alamofire'.

1. Open your .xcworkspace file in Xcode.
2. Use global find (Cmd + Shift + F) to search for references to the deleted module:

// Delete imports across your project
import Alamofire

3. Replace any implementation calls that depended on that library with native Foundation/Swift standard library equivalents (such as URLSession) or an alternative dependency.
4. Clean the Xcode build folder to discard precompiled modules: press Cmd + Shift + K or select Product > Clean Build Folder.
5. Build the project (Cmd + B) to ensure compilation succeeds.

3. Completely remove CocoaPods from the project (Optional)

If you want to remove all pods and revert your project back to a standard .xcodeproj—for instance, when migrating to Swift Package Manager (SPM)—use CocoaPods’ built-in deintegration tool.

1. Close Xcode.
2. In Terminal, navigate to the project directory and run:

pod deintegrate

This command strips the Xcode project of all CocoaPods build phases, integrated libraries, and workspace hooks without modifying your source code.

3. Delete the leftover CocoaPods artifacts:

rm -rf Podfile.lock Pods/ MyApp.xcworkspace

4. If you no longer need CocoaPods manifests at all, remove the Podfile as well:

rm Podfile

5. Open your native MyApp.xcodeproj directly. Open the Project Navigator, select your application target, go to Build Phases, and verify that [CP] Embed Pods Frameworks, [CP] Check Pods Manifest.lock, and [CP] Copy Pods Resources have been cleared.

How to prevent it

• Never delete files inside Pods/ manually: Let pod install manage the contents of the Pods directory based on your Podfile.
• Use pod install instead of pod update: Using pod install removes deleted pods without triggering unwanted upgrades across all your remaining libraries.
• Commit Podfile and Podfile.lock together: When removing a library, commit both files in the same pull request to prevent dependency mismatches across your development team.
• Verify dependencies before removal: Ensure other internal targets or shared frameworks do not rely on the pod you are removing before you delete it.

FAQ

What is the difference between pod install and pod update when removing a library?

Running pod install only processes changes between your Podfile and your existing Podfile.lock, removing only the deleted library while keeping everything else on their current versions. Running pod update will remove the deleted pod, but it will also attempt to upgrade every other pod in your project to its latest allowed version.

Why do I get “ld: framework not found” after removing a pod?

This usually occurs because Xcode is building from cached build artifacts, or you manually removed files instead of letting pod install remove the target. Run Product > Clean Build Folder (Cmd + Shift + K), quit Xcode, and re-run pod install in your terminal.

Do I need to delete the Pods folder before running pod install?

No, deleting the Pods folder manually is unnecessary. CocoaPods automatically inspects which dependencies are missing from the Podfile and deletes only the redundant framework folders and build targets.