---
name: cocoapods-setup
description: Install and configure CocoaPods dependency manager for iOS/macOS projects — setup, Podfile, troubleshooting, and best practices
license: MIT
compatibility: opencode
metadata:
  platform: macos
  category: ios
---

## What I do

Guide the installation, configuration, and usage of CocoaPods — the dependency manager for Swift and Objective-C Cocoa projects.

## When to use me

Use this skill when the user wants to:
- Install CocoaPods on a new Mac
- Initialize CocoaPods in an existing iOS/macOS project
- Fix CocoaPods installation or build errors
- Add or update dependencies via Podfile
- Migrate from manual dependency management to CocoaPods
- Troubleshoot common CocoaPods issues

## Workflow

### Step 1: Check if CocoaPods is already installed

```bash
pod --version
which pod
```

### Step 2: Install CocoaPods

**Option A — System-wide via gem (simplest):**
```bash
sudo gem install cocoapods
pod setup
```

**Option B — Homebrew (recommended, cleaner):**
```bash
brew install cocoapods
pod setup
```

**Option C — Bundler (project-specific, best practice for teams):**

Create `Gemfile` in the iOS/macOS project root:
```ruby
source 'https://rubygems.org'

gem 'cocoapods', '~> 1.15'
gem 'fastlane'
```

Install via bundler:
```bash
gem install bundler
bundle install
bundle exec pod install    # Always use bundle exec going forward
```

**After installation, verify:**
```bash
pod --version
```

### Step 3: Initialize CocoaPods in a project

Navigate to the `.xcodeproj` parent directory:

```bash
pod init
```

This creates a `Podfile`.

### Step 4: Configure Podfile

Basic Podfile structure:

```ruby
# Minimum iOS version
platform :ios, '15.0'
# Or for macOS:
# platform :osx, '12.0'

target 'YourApp' do
  use_frameworks!

  # Pods go here
  pod 'Alamofire', '~> 5.9'
  pod 'SnapKit', '~> 5.7'
  pod 'Kingfisher', '~> 7.12'

  # Target-specific pods
  target 'YourAppTests' do
    inherit! :search_paths
    pod 'Quick'
    pod 'Nimble'
  end

  target 'YourAppUITests' do
    # UI test pods
  end
end
```

**Common Podfile patterns:**

```ruby
# Disable the master specs repo (faster)
install! 'cocoapods', :deterministic_uuids => false

# Post-install hook for build settings
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
      config.build_settings['ENABLE_BITCODE'] = 'NO'
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
    end
  end
end

# Specific source URL (private pods)
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/your-org/private-specs.git'

# Local pod
pod 'MyCustomPod', :path => '../MyCustomPod'
```

### Step 5: Install dependencies

```bash
pod install
# or with bundle:
bundle exec pod install
```

**Important:** After `pod install`, always open the `.xcworkspace` file, NOT `.xcodeproj`:

```bash
open YourApp.xcworkspace
```

### Step 6: Update dependencies

```bash
# Update specific pod
pod update Alamofire
bundle exec pod update Alamofire

# Update all pods
pod update
bundle exec pod update

# Update and clean
pod deintegrate && pod install
```

### Step 7: Common commands

```bash
# List outdated pods
pod outdated

# Search for pods
pod search "networking"
# Or use website: https://cocoapods.org

# Check pod cache
pod cache list

# Clear cache
pod cache clean --all

# Show pod info
pod spec cat Alamofire

# Check installed versions
pod outdated --no-repo-update
```

### Step 8: Creating a Podspec (for publishing)

```bash
pod spec create YourLibrary
```

Edit `YourLibrary.podspec`:
```ruby
Pod::Spec.new do |s|
  s.name         = 'YourLibrary'
  s.version      = '1.0.0'
  s.summary      = 'A short description'
  s.homepage     = 'https://github.com/username/YourLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/YourLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.swift'
  s.swift_version = '5.0'
  s.ios.deployment_target = '15.0'
end
```

Validate:
```bash
pod lib lint
```

Publish:
```bash
pod trunk push YourLibrary.podspec
```

### Step 9: Using multiple build configurations

```ruby
# Podfile
pod 'Firebase/Analytics'
pod 'Firebase/Crashlytics', :configurations => ['Debug', 'Release']

# Exclude pod from certain configurations
pod 'Reveal-SDK', :configurations => ['Debug']
```

### Step 10: Git considerations

**Recommended `.gitignore` additions:**
```
# CocoaPods
Pods/
*.xcworkspace
Podfile.lock
```

**Opinion split on committing Pods:**
- **Commit Pods/**: Reproducible builds, no dependency on CocoaPods being installed on CI
- **Don't commit Pods/**: Smaller repo, CI must run `pod install`

The `Podfile.lock` should ALWAYS be committed — it pins exact versions used.

### Step 11: CI/CD setup

```yaml
# GitHub Actions example
- name: Install CocoaPods
  run: |
    gem install cocoapods
    pod install

# Fastlane example
lane :build do
  cocoapods(
    clean: true,
    podfile: "./Podfile"
  )
end
```

## Troubleshooting

| Error | Solution |
|-------|----------|
| `pod: command not found` | CocoaPods not installed or not in PATH. Reinstall: `brew install cocoapods` |
| `Unable to find a specification` | Clear specs repo: `pod repo remove master && pod setup` |
| `The sandbox is not in sync` | Clean and reinstall: `pod deintegrate && pod install` |
| `CocoaPods could not find compatible versions` | Run `pod update <pod-name>`, check iOS version in Podfile matches Xcode target |
| `Failed to connect to GitHub` | Network issue or GitHub down. Try `pod install --verbose` for details |
| `gem install fails with permission error` | Use sudo or install via Homebrew instead of system Ruby gem |
| `wrong Ruby version error` | Install appropriate Ruby: `brew install ruby`, use `rbenv` or `rvm` |
| `Sending stats - NoMethodError` | Run `pod install --no-repo-update` to skip repo indexing |
| `No such module 'PodName'` | Open `.xcworkspace` not `.xcodeproj`, or run `pod deintegrate && pod install` |
| `Library not loaded: @rpath/Framework.framework` | Add to Podfile: `use_frameworks! :linkage => :static` |
| `Xcode project was regenerated` warnings | Normal after `pod install`, commit both `.xcodeproj` and `.xcworkspace` |
| `Apple Silicon / M1/2/3 Mac issues` | Run with Rosetta: `arch -x86_64 pod install`, or ensure all pods support arm64 |
| `The version of CocoaPods used to generate the lockfile is higher` | Update CocoaPods: `gem update cocoapods` and run `pod install` again |

## Key notes for the agent

- **Use Homebrew over gem when possible** — avoids system Ruby permission issues and is easier to manage.
- **Never modify Podfile manually without checking current content** — first read the existing Podfile.
- **`pod install` vs `pod update`**: `install` respects Podfile.lock versions; `update` fetches latest within version constraints. Teach the user the difference.
- **Always remind the user to open `.xcworkspace`** after `pod install`. This is the #1 beginner mistake.
- **For Apple Silicon Macs**: Some pods may need Rosetta. Suggest `arch -x86_64 pod install` if encountering arm64 compatibility issues.
- **Podfile syntax is Ruby** — validate with `pod install --verbose` if errors occur.
- **CI pipelines**: Consider committing the Pods directory if reproducibility is critical. Otherwise, run `pod install` in CI.
- CocoaPods requires **Xcode and Xcode Command Line Tools** to be installed first:
  ```bash
  xcode-select --install
  ```