CocoaPods: Podfile, Install & Version Resolution

CocoaPods is a dependency manager for Swift/Objective-C projects. It reads a Podfile, resolves versions against the public Specs registry (or a git/local source), and generates an Xcode workspace wiring your app together with a separate Pods project.

Podfile Basics

# Podfile
platform :ios, '15.0'
use_frameworks!  # required for pods containing Swift code

target 'MyApp' do
  pod 'Alamofire', '~> 5.8'        # optimistic operator: >= 5.8.0, < 6.0.0
  pod 'SwiftyJSON', '5.0.1'         # exact version pin
  pod 'SDWebImage'                  # any version

  target 'MyAppTests' do
    inherit! :search_paths
    pod 'Quick'
    pod 'Nimble'
  end
end

# Local, in-development pod (path relative to the Podfile)
pod 'MyInternalKit', :path => '../MyInternalKit'

# Pull directly from a git ref instead of the published registry
pod 'SomeFork', :git => 'https://github.com/user/repo.git', :branch => 'fix/crash'

# Only pull in a subset of a library's functionality
pod 'Firebase/Auth'
pod 'Firebase/Firestore'

Installing & Updating

# First-time setup (or after cloning a repo with an existing Podfile.lock)
gem install cocoapods    # or: brew install cocoapods
pod install

# install respects Podfile.lock — only resolves what's not already pinned.
# Safe for CI: reproducible, doesn't silently bump versions.
pod install

# update re-resolves within the Podfile's constraints, ignoring the lock
# file, and rewrites it. Use deliberately, not in CI.
pod update                # update everything
pod update Alamofire       # update just one pod

# See what's outdated without changing anything
pod outdated

# ALWAYS open the .xcworkspace, never the standalone .xcodeproj —
# the workspace links your app's project with the generated Pods project
open MyApp.xcworkspace

Podfile.lock & Reproducibility

• Podfile.lock records the exact resolved version of every pod (and transitive dependency) actually installed — commit it to git.

• Podfile expresses constraints ("5.8 or newer, below 6.0"); Podfile.lock pins the specific version that satisfied them at install time.

• Two developers running `pod install` against the same Podfile.lock get byte-identical dependency versions, regardless of what's newest on the registry that day.

• `Pods/` (the actual downloaded source) is typically gitignored — Podfile.lock alone is enough to reproduce it via `pod install`.

• CI pipelines should run `pod install`, never `pod update` — update deliberately changes what's pinned.

Troubleshooting

# Full reset when the Xcode project's CocoaPods integration is broken
pod deintegrate           # strips CocoaPods build settings from the .xcodeproj
rm -rf Pods Podfile.lock
pod install                # clean reinstall

# Clear the local pod cache (downloaded source, separate from Pods/)
pod cache clean --all

# Verbose install output when a resolution or build step fails silently
pod install --verbose

# Repair references after an Xcode version bump or corrupted workspace
pod install --repo-update  # also refreshes the local Specs mirror first