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:
- Check the spelling and version in your
Podfile. Verify the version exists on the pod’s GitHub releases or onhttps://cocoapods.org/pods/Alamofire. - Update specs:
pod install --repo-update
- If you use a private spec repo, make sure your
Podfiledeclares 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
- 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
cdinto the folder containing yourPodfilebefore runningpod installorpod update.pod repo updateworks from anywhere, but keeping the habit avoids confusion. - Prefer
pod install --repo-updateover a standalonepod repo updateso specs are only updated when you actually need to resolve dependencies. - Do not commit
~/.cocoapods/reposorPods/confusion to git. CommitPodfileandPodfile.lock, ignorePods/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 updateorpod install --repo-updatestep when you add a new pod version, so CI does not fail withNone 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.
Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.