Five Steps to Migrate an iOS Project From CocoaPods to Carthage

DZone 's Guide to

Five Steps to Migrate an iOS Project From CocoaPods to Carthage

There's more than one dependency management tool for iOS. If you've decided to switch to Carthage, follow these steps to migrate your projects.

· Mobile Zone ·
Free Resource

Apple may not like the fact that iOS developers are adding third-party dependencies to iOS projects. Apple's core technologies have provided enough frameworks and tools with healthy documentation that developers can use to build and distribute iOS apps. This might be the reason Apple didn't have any official package manager to manage dependencies for iOS apps yet. However, this is not the reality; iOS developers want to share and distribute code for reusability, avoid duplication, and save time.

CocoaPods has been serving as a dependency management solution for iOS apps for a long time. It's written in Ruby and iOS developers need to know Ruby in order to use it. As long as it works, everything is OK, but the pain starts if something breaks in CocoaPods or the magical settings that CocoaPods has done inside the Xcode project. Carthage is another dependency management solution which is written in Swift and maintained by GitHub engineers. In my last blog post, I explained the difference between CocoaPods and Carthage and how to choose the right framework. I would strongly recommend reading that post to understand the basic difference. In this post, we will assume that you have decided to go to Carthage and we will see how easy it is to migrate from CocoaPods to Carthage. It can be easily achieved by applying these five steps:

  • Dependency Analysis
  • Carthage Dry Run
  • CocoaPods Decommissioning
  • Cleaning Xcode Project
  • Linking Frameworks to the targets

We will discuss each phase in detail. One thing to note here: we are only talking about the Swift frameworks and dynamic libraries, not about the old Objective-C or static frameworks.

1. Dependency Analysis

The first step to migrate the iOS project to Carthage is dependency analysis. If you are using CocoaPods, then there must be a list of dependencies hanging there inside the Podfile of the iOS project. In the analysis phase, you should do two major things.

Ditch Unwanted Dependencies

At this stage, try to get rid of the dependencies that you no longer using or can be replaced with another approach if possible. An example would be SwiftLint; think, why do we need to add SwiftLint as a dependency to an iOS app? It can be easily run on a GitHub pre-commit hook or from a command line script on the local machine or Continuous Integration server. Similarly, check how many other dependencies are being used and see if those can easily be replaced by native Apple technologies like Alamofire Or SwiftyJSON can be replaced by URLSession and Codable. Fewer dependencies, less hassle.

Check Carthage Support

Almost all the major third-party Swift frameworks support Carthage. The way to check that is to visit the GitHub repo page of the framework and look at the README file. There should be a badge stating the Carthage support as well the platform support, as shown below (not that big, though)

If you don't see the badge there and it's a Swift framework that can be built with xcodebuild and have schemes supported by the iOS platform, then that should be OK as well. Once you confirm these both things, you can go ahead and run next step, which is the Carthage dry run.

2. Carthage Dry Run

At this stage, you have confirmed that dependencies that you need to migrate from CocoaPods to Carthage have been supported. It's time to prepare the Cartfile and add all the dependencies there with correct versions mentioned either in the Podfile or Podfile.lock. Once the Cartfile is prepared, try running the Carthage update on the current project:

$ carthage update --platform iOS

After this command, it might be time for a coffee break. When you return from your coffee break and everything has been successfully built, then you are good to go to the next step. However, if you are stuck with errors, it's a good time to fix those errors. The common errors are

  • The Swift version might be different.
  • The framework does not support the iOS platform or doesn't build with Carthage in mind.
  • Or, any other error that has been specified by Carthage.

Once everything is successfully built, you should have a Carthage directory with Checkout and Build subdirectories with all the source code of the dependency frameworks and pre-built frameworks. At this stage, you are good to ditch CocoaPods from your iOS project.

3. CocoaPods Decommissioning

When you integrated CocoaPods into your iOS project, you might have observed that CocoaPods almost invaded your Xcode project. CocoaPods not only created Xcode Workspace, but also penetrated deep into the build settings and build phases. The process of removing all the mess from your iOS project sounds like yak shaving, but it's not. There is no need to manually delete the CocoaPods files, scripts, and frameworks. Big thanks to the CocoaPods-Deintegrate plugin that removes almost all marks that CocoaPods puts inside Xcode projects. We just need to download the plugin and run the pod deintegrate script from the root of the iOS project or where your Xcode project or workspace is located.

$ [sudo] gem install cocoapods-deintegrate
$ pod deintegrate

There is no need to reinvent the wheel as long this script works, but it's important to understand what this script is doing under the hood. In summary, this script does the following things:

  • Deletes CocoaPods-specific scripts from the build phases of each target. The scripts are usually "Copy Pod Resources," "Check Pod Manifest.lock," and "Embed Pods Frameworks."
  • Removes Pod Libraries from the build phases libPods-.a .
  • Deletes Pod file references from the project, including .a files as well as all the .xcconfig files for all the targets.
  • Deletes Pod groups from the Xcode project.

If you know Ruby, then feel free to have a look at this deintegrator.rb file on GitHub, or you can write your own scripts in bash or Python to remove the above things. Again, we can do the above steps manually as well, but the automated way mentioned above will save your day for sure.

4. Clean XCode Project

As you have seen above, we have almost removed the references of CocoaPods in the previous step, but there are still some CocoPods marks in our Xcode project that we need to remove manually. The CocoPods-Deintegrate plugin doesn't remove the following things:

  • Xcode Workspace
  • Podfile and Podfile.lock files
  • The values attached to build configurations, like COCOAPODS=1 

We have to delete those things manually or using scripts. There is another plugin, cocoapods-clean, to remove workspace and Podfile, but its very easy to delete it manually. You can also cross-verify the Xcode project to see if there are any custom settings left behind.

Once you are done with the above steps, you are completely CocoaPods-free. You have successfully removed the elephant from your iOS project. Yay!

5. Link Frameworks to Targets

This is the last step of the migration from CocoaPods to Carthage. At this point, you might have the Carthage/Checkout directory with the source code of the dependencies and the Carthage/Checkout directory with all the built .framework bundles. Now we have to link all these frameworks to the respective targets, as mentioned in the Carthage documentation here. This is a bit of manual process, but we have to do it only once. However, this gives you full control of the dependencies and you know what you are doing instead of the magic happening under the hood.

Once you have linked all the frameworks to targets as per the old Podfile and added the Carthage copy-frameworks scripts, all your projects and dependencies should works as they were working with CocoaPods. Once you confirm that everything is working as expected and nothing is broken as part of these steps, this is the time to celebrate your new tool written in Swift. No Ruby and no magic under the hood.

Things to Remember

Now that, we have seen the steps to migrate your iOS app to use Carthage. There are certain things to remember about Carthage:

  • The idea of Carthage is based on frameworks. Carthage only supports dynamic Swift frameworks, not static libraries. In the future, you will only able to add dynamic Swift frameworks as dependencies. You can still add static dependency source code using the --no-build option, but it's not the way you should use Carthage.
  • Carthage is designed for Swift. If you are still dealing with some Objective-C, then fix that first before moving to Carthage.
  • Migrating from CocoaPods to Carthage doesn't solve the problems within iOS apps. It just allows you to take control of your Xcode project and frees you from dealing with Ruby problems.

There are various benefits of using Carthage over CocoaPods. You can refer to the previous post on Carthage vs. CocoaPods for a detailed comparison.


Removing CocoaPods is not as big a task as you might think; using these simple five steps, we can get rid of CocoaPods from an iOS project completely and use a Swift-based dependency management solution for iOS apps. This could be the first step of removing Ruby from iOS apps. Carthage will give you less hassle and full control of your Xcode project. Have you recently migrated to Carthage from CocoaPods? What are your experiences?

carthage, cocoapods, ios, mobile, mobile app development

Published at DZone with permission of Shashikant Jagtap , DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}