Complete Guide to Removing CocoaPods from iOS Projects

Background and Motivation for CocoaPods Removal

CocoaPods, as a popular dependency management tool in iOS development, provides developers with convenient integration solutions for third-party libraries. However, in certain scenarios, developers may need to completely remove CocoaPods from their projects. Common reasons include client technical restrictions, project architecture adjustments, migration to alternative dependency management solutions (such as Swift Package Manager), or simplifying project structure to use a single xcodeproj file instead of xcworkspace.

Detailed Steps for Manual CocoaPods Removal

For developers who prefer complete control over the removal process, manual removal remains the most reliable approach. Below is the detailed procedure based on CocoaPods version 0.39.0:

Preparation and Important Considerations

Before performing any removal operations, it is strongly recommended to commit the project to a version control system (such as Git). This ensures quick recovery to the previous state in case of operational errors. Additionally, verify the current CocoaPods version being used, as integration methods may vary across different versions.

Step 1: Delete CocoaPods-Related Files

Begin by removing the core configuration files generated by CocoaPods:

rm Podfile
rm Podfile.lock
rm -rf Pods

These files contain the project's dependency configuration information and installed third-party libraries. Deleting them will clear the foundation of CocoaPods configuration.

Step 2: Clean Workspace Files

If the project uses a workspace generated by CocoaPods, remove the corresponding file:

rm YourProject.xcworkspace

Step 3: Clean Xcode Project Configuration

Open the main project's xcodeproj file and perform the following cleanup operations in Xcode:

• In the project navigator, delete references to the Pods.xcconfig file
• In the Frameworks group, remove references to the libPods.a static library

Step 4: Remove Build Phases

In the project's Build Phases, delete the following build phases automatically added by CocoaPods:

• Copy Pods Resources
• Embed Pods Frameworks
• Check Pods Manifest.lock

Step 5: Handle Third-Party Library Dependencies

After removing CocoaPods, alternative integration solutions must be found for third-party libraries used in the project. Options include manual library file integration, using Swift Package Manager, or completely removing dependencies that are no longer needed.

Simplifying Removal with Automated Tools

For developers seeking to streamline the removal process, the CocoaPods community provides dedicated plugins to automate this procedure.

Installing Necessary Tools

First, install the cocoapods-deintegrate and cocoapods-clean plugins:

sudo gem install cocoapods-deintegrate cocoapods-clean

Executing Automated Removal

Use the following command sequence to complete automated removal:

pod deintegrate
pod cache clean --all
pod clean
rm Podfile
rm Podfile.lock

The pod deintegrate command automatically handles configuration references and build phases in the Xcode project, while pod clean cleans up remaining CocoaPods files. It's important to note that cocoapods-deintegrate is a third-party plugin maintained by CocoaPods core team members. While it generally maintains compatibility with the latest versions, it's advisable to verify compatibility before use.

Alternative Approach: Retaining CocoaPods with Simplified Project Structure

If the primary reason for removing CocoaPods is the desire to use a single xcodeproj instead of xcworkspace, consider using the --no-integrate flag:

pod install --no-integrate

This approach generates a Pods.xcodeproj file instead of a workspace. This xcodeproj can then be added as a subproject to the main project, preserving CocoaPods' dependency management functionality while meeting the requirement for a single project file.

Verification and Testing

After completing removal operations, comprehensive verification is essential:

• Clean the project (Product > Clean Build Folder)
• Recompile the project to ensure no compilation errors
• Run the project to verify all functionality works correctly
• Check console output to confirm no missing dependency warnings

Conclusion and Best Practices

Removing CocoaPods is a process that requires careful execution. Whether choosing manual removal or automated tools, the process should be performed in a version-controlled environment with complete backups. When migrating to alternative dependency management solutions, a gradual approach is recommended—starting with less critical dependencies and verifying success before handling core dependencies.

With the increasing maturity of Swift Package Manager, more projects are choosing to migrate from CocoaPods. Regardless of the chosen solution, ensuring that the project's dependency management approach aligns with the team's technical stack and long-term maintenance requirements remains the most important consideration.