CocoaPods and Carthage caches: location and cleanup

Part of: Mac disk cleanup for developers: every cache, what it costs to rebuild (Developers)

CocoaPods and Carthage both keep a copy of the libraries they download, so a second project that needs the same library does not download it again. Both caches are safe to delete. The cost is a re-download, and for Carthage a rebuild.

CocoaPods and Carthage are older dependency tools for iOS and Mac projects. Swift Package Manager is the newer built-in one, covered in its own guide. Many projects still use the older tools.

Where the files are

Defaults, which can be changed:

• CocoaPods downloads: a CocoaPods folder in ~/Library/Caches.
• CocoaPods spec repositories: a hidden .cocoapods folder in your home folder. A spec is a small file that describes one library version. The repository of them can be large on an old install.
• Carthage: a folder named org.carthage.CarthageKit in ~/Library/Caches, plus a Carthage folder in each project that holds the built frameworks.
• Inside a project: a Pods folder next to the project holds the pods that project actually uses.

To see the sizes of the ones that exist on your Mac:

du -sh ~/.cocoapods ~/Library/Caches/CocoaPods ~/Library/Caches/org.carthage.CarthageKit

A folder you never used prints an error, which is fine. On the Mac used to check this article, CocoaPods and Carthage were not installed, so the spec folder was small and the cache folders were absent. Sizes on a Mac that has used them for years will differ.

Safe, risky, never

• Safe: the download caches in ~/Library/Caches. Cost: a download of each library on next install.
• Risky: the Pods folder in a project you must build offline soon. Also risky: removing the spec repository when you are offline, since CocoaPods needs it to resolve versions.
• Never: do not delete Podfile, Podfile.lock or Cartfile.resolved. Those files pin your versions and belong to the project, not to the cache. Do not edit files inside Pods and then delete the folder: edits are lost.

What clearing costs

For CocoaPods, the next time you install pods, CocoaPods fetches libraries again, and the cache fills up again. The lock file keeps you on the same versions. If a library was removed from its host, you may not be able to get it again, so check that your lock file works before deleting old caches for a project you must keep building.

For Carthage, the cost is higher. Carthage builds each dependency into a framework on your Mac, which can take a long time for large libraries. Deleting the caches means that work runs again. Prebuilt binaries, where a library offers them, are quicker to download.

How to clear them

1. Quit Xcode.
2. Look at the sizes with the command above.
3. For CocoaPods, move the CocoaPods folder in ~/Library/Caches to the Trash. CocoaPods also has its own cache command, described in its documentation.
4. For Carthage, move the org.carthage.CarthageKit folder to the Trash.
5. Empty the Trash. See why the Trash does not free space.
6. Install dependencies in your project again when you next work on it.

The Pods folder in each project

Each project that uses CocoaPods has a Pods folder. It is recreated from the Podfile. Many teams do not commit it. If yours does, do not delete it without checking your version control first, because it may be the only copy of the exact code you ship.

Related Xcode build folders are covered in Cleaning up Xcode, and the overall list is in the developer cleanup guide.

Worked example: what the spec folder looks like

Run this read-only command:

ls -la ~/.cocoapods

On the Mac used to check this article, it held a single repos folder and nothing else. That is the spec repositories described above. It is the part CocoaPods needs to work out which versions exist, so on a Mac that uses CocoaPods you should leave it alone unless you are sure you can go online and fetch it again.

The CocoaPods command line tool itself was not installed on that Mac, so we did not run any pod command. Any pod command you find online is UNVERIFIED here. Check the CocoaPods documentation for your version before you run one.

Check the lock file first

Before you clear anything for a project you must keep building, confirm that Podfile.lock is in the project and committed. That file lists the exact version of every pod. With it, a fresh install gives you the same versions. Without it, CocoaPods picks the newest version that fits the Podfile, and you may get different code from what you shipped.

If something goes wrong

• Pod install cannot find a version. The spec repository is missing or old. Go online and let CocoaPods update it, then run the install again.
• The build fails after a reinstall with errors in a pod. The version changed. Compare Podfile.lock with your last working commit.
• Carthage rebuilds take hours. That is the cost of building each dependency yourself. Use prebuilt binaries where a library offers them.
• A private pod fails to download. Your credentials or network access are missing. Fix that before you clear anything else.

When not to clean

Do not clear these caches on a project that you maintain but rarely build, if its libraries come from servers that may be gone. The cache can be the last copy. Make sure the project builds from a clean checkout on another machine first.

See sizes in a scan

DiskJoy is our product. Its scan reads your disk and shows how large these folders are, without changing anything. Cleanup is not built yet, so DiskJoy does not remove them today.