Fix: pod repo update Takes Forever and Confuses Folders in Xcode

Written by

in

Quick answer: pod repo update does not touch your project or Documents folder. It only runs git pull on the spec repos cloned at ~/.cocoapods/repos, usually https://github.com/CocoaPods/Specs. Your project code is only downloaded when you run pod install or pod update.

Running pod repo update from your Documents folder and seeing thousands of create and delete lines for 20 minutes is alarming. It looks like it rewrote your whole Mac, but it did not.

Why this happens

CocoaPods keeps a local copy of every available pod version, not the pod code itself. That copy is called a spec repo and it lives outside your project at ~/.cocoapods/repos in your home folder.

By default you have one spec repo named cocoapods (older installs call it master) that is a git clone of https://github.com/CocoaPods/Specs. Inside it is a folder for every pod, with a subfolder for every version, each containing a .podspec.json file. A PodSpec describes where to fetch the source, which tag or commit to use, which files to compile, and metadata like name and version. For example:

spec.source = { :git => 'https://github.com/Alamofire/Alamofire.git', :tag => '5.8.1' }

When you run pod repo update, CocoaPods does this:

Updates the local clone of the spec-repo NAME. If NAME is omitted this
will update all spec-repos in ~/.cocoapods/repos.

It is just a git pull on that clone. The current directory where you run the command does not matter. Whether you run it in ~/Documents, ~/Desktop, or inside your Xcode project, it always updates ~/.cocoapods/repos and nothing else.

Why it takes so long and prints so much: the master Specs repo contains specs for every version of every pod ever published. A pull has to fetch and merge thousands of new and deleted spec files. That is the create and delete output you saw. It is not creating or deleting your documents.

Your actual project dependencies are not downloaded by pod repo update. They are downloaded later when you run pod install or pod update, which reads your Podfile and Podfile.lock, resolves versions against the local spec repos, then fetches the real source code into Pods/ inside your project.

Since CocoaPods 1.7.2/1.8, new installations default to a CDN (https://cdn.cocoapods.org/) instead of the git spec repo, so many developers never need pod repo update at all. If you still have the git repo, the command is still valid but much slower.

How to fix it

1. Verify that your Documents folder was not modified

You do not need to restore anything. Confirm where CocoaPods actually wrote:

# See which spec repos you have and where they live
pod repo

# Example output:
# cocoapods
# - Type: git (remotes/origin/master)
# - URL:  https://github.com/CocoaPods/Specs
# - Path: /Users/yourname/.cocoapods/repos/cocoapods

# Check the last update time of the spec repo
ls -lt ~/.cocoapods/repos

# See what git actually pulled
cd ~/.cocoapods/repos/cocoapods
 git log --oneline -10
 git status

If you want to be extra sure nothing in Documents changed, check recent modifications there. pod repo update will not show up in that folder’s git history because it never touched it.

2. Update specs the right way for your project

You rarely need a blind pod repo update for all repos. Use a more targeted command from inside your project folder (where your Podfile is):

Option A: Update specs as part of install (recommended)

cd /path/to/YourProject  # folder that contains Podfile
pod install --repo-update

This updates the spec repos first, then resolves and installs exactly what your Podfile asks for. It is the same as running pod repo update followed by pod install, but in one step and it ensures the specs are fresh before resolving.

Option B: Update only one spec repo

If you know you only need the main repo:

pod repo update cocoapods
# or on older installs:
pod repo update master

List your repo names first with pod repo so you use the correct name.

Option C: Update a single pod without updating all specs

If you already have fresh specs and just want a newer version of one pod:

pod update Firebase/Core --verbose
# or
pod update Alamofire

pod update PODNAME ignores Podfile.lock for that pod and pulls the latest version allowed by your Podfile. pod install respects Podfile.lock and is for clean installs.

3. Fix the error that usually makes you run pod repo update

You will often see:

None of your spec sources contain a spec satisfying the dependencies:
`Alamofire (= 11.0.3)`.

You have either:
 * out-of-date source repos which you can update with `pod repo update` or with `pod install --repo-update`.
 * mistyped the name or version.
 * not added the source repo that hosts the Podspec to your Podfile.

This means your local spec clone does not know about that version yet. Fix it in order:

  1. Check the spelling and version in your Podfile. Verify the version exists on the pod’s GitHub releases or on https://cocoapods.org/pods/Alamofire.
  2. Update specs:
pod install --repo-update
  1. If you use a private spec repo, make sure your Podfile declares it at the top:
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/your-company/PrivateSpecs.git'

platform :ios, '15.0'
use_frameworks!

target 'YourApp' do
  pod 'Alamofire', '5.8.1'
  pod 'Firebase/Core'
end
  1. Then install again:
pod install

4. Reduce the wait time going forward

If pod repo update is consistently slow, you are on the old git-based Specs clone. Two options:

# Check CocoaPods version
pod --version

# Update CocoaPods itself
gem install cocoapods
# or with Homebrew
brew upgrade cocoapods

Newer CocoaPods versions use the CDN by default and do not need a full git clone. For existing projects, you can remove the git repo and let CocoaPods use the CDN. CocoaPods will fetch only the specs it needs instead of pulling the entire history:

pod repo remove master
# or
pod repo remove cocoapods
pod install --repo-update

Only do this if your Podfile does not rely on a custom git spec repo that you still need.

How to prevent it

  • Always cd into the folder containing your Podfile before running pod install or pod update. pod repo update works from anywhere, but keeping the habit avoids confusion.
  • Prefer pod install --repo-update over a standalone pod repo update so specs are only updated when you actually need to resolve dependencies.
  • Do not commit ~/.cocoapods/repos or Pods/ confusion to git. Commit Podfile and Podfile.lock, ignore Pods/ if your team prefers, but never ignore the spec repo location.
  • Keep CocoaPods updated so you benefit from the CDN and avoid the 20-minute git pull.
  • If you have CI, add an explicit pod repo update or pod install --repo-update step when you add a new pod version, so CI does not fail with None of your spec sources contain a spec.

FAQ

Does pod repo update modify my project or Documents folder?

No. It only updates the cloned spec repos under ~/.cocoapods/repos. It does not create, delete, or edit files in the directory where you run it. Your Xcode project is only changed by pod install and pod update, which write to Pods/ and Podfile.lock inside your project.

Why does pod repo update take 20 minutes and print thousands of lines?

Because the Specs repo tracks every version of every pod. A git pull has to download and merge thousands of small .podspec.json files. The create and delete lines are git reporting spec files, not your personal files. Using the CDN in newer CocoaPods avoids this full clone.

Should I use pod repo update or pod install –repo-update?

Use pod install --repo-update when you are working on a project. It updates specs and then installs in one correct order. Use pod repo update or pod repo update [NAME] only when you want to refresh specs without touching any project, for example to fix CI or to inspect specs manually.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.