CocoaPods Plugin — What It Is, a Plugin for KMM, and Setup

What is CocoaPods Plugin?

CocoaPods Plugin (also known as kotlin.cocoapods) is an official JetBrains plugin for integrating CocoaPods with Kotlin Multiplatform Mobile. The plugin is part of the Kotlin Gradle DSL and is configured directly in the build.gradle.kts of the KMM module. It automates the creation and maintenance of the Podfile, generation of .xcworkspace, and management of pod dependencies, eliminating the need for manual Xcode project configuration.

Before CocoaPods Plugin, KMM developers had to manually create a Podfile, run pod install, configure bridge headers, and track pod versions separately from Gradle dependencies. This led to version desynchronization and difficulties in CI/CD pipelines. The plugin solved these problems by making iOS dependency management as simple as managing Gradle dependencies in Android modules.

The plugin supports both public pods from CocoaPods Trunk and custom pods from private repositories. Working with local Podspec and git-based repositories is also supported. The plugin is compatible with Kotlin 1.6.0 and above, and requires CocoaPods (gem install cocoapods) to be installed on the development machine.

How CocoaPods Plugin Works

CocoaPods Plugin operates at the Gradle task-graph level, adding specialized tasks for working with CocoaPods. The main tasks include podInstall (installing pods), podGenXcodeWorkspace (generating .xcworkspace), and podBuildDebugFramework (building a Debug version of the framework). The plugin analyzes the cocoapods section in build.gradle.kts, creates a Podfile based on declared dependencies, and runs pod install with the necessary parameters.

The plugin architecture includes three components: a DSL extension for build.gradle.kts, a Podfile Generator for creating the Podfile, and an Xcode Integration Layer for configuring .xcworkspace. The DSL extension provides a cocoapods { } block with nested pod() functions for declaring dependencies, specRepo() for specifying private repositories, and framework { } for configuring the output framework. The Podfile Generator translates these declarations into Ruby syntax understood by CocoaPods.

kotlin {
    cocoapods {
        summary = "Shared module for iOS project"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = true
            export(project(":core"))
        }
        pod("Alamofire") {
            version = "~> 5.9"
        }
        pod("Kingfisher") {
            version = "7.12"
        }
    }
}

PodInstall Task Lifecycle

When executing podInstall, the plugin sequentially: generates a Podfile in the project root, runs pod install via the command line, generates .xcworkspace, checks that pod versions match the declared ones, and caches Podfile.lock. On subsequent runs without configuration changes, podInstall is skipped if Podfile.lock has not changed. This saves time in CI/CD, where pod install can take up to 2-3 minutes for a clean installation.

Setting Up CocoaPods Plugin in a KMM Project

Setting up CocoaPods Plugin requires several steps. Installing CocoaPods on the development machine (gem install cocoapods) is a prerequisite. Then, in the build.gradle.kts of the shared module, add a cocoapods { } block with framework configuration and dependencies. After configuration, run the podInstall task, which will create the Podfile and install the pods. The generated .xcworkspace will be located in the project root next to the Podfile.

The plugin integrates with Xcode Build Phases. When building an iOS app, Xcode runs embedAndSignAppleFrameworkForXcode — a task that copies the Kotlin/Native framework into the app bundle. CocoaPods Plugin adds this build phase automatically when generating .xcworkspace. If .xcworkspace was generated, it must be opened instead of .xcodeproj for correct builds with pod dependencies.

Code Examples: Pod Configuration

Let us look at various scenarios for declaring pods in CocoaPods Plugin. The basic case is connecting a public pod from CocoaPods Trunk with a specified version. More complex scenarios include using custom podspec, local pods, and pods from git repositories.

kotlin {
    iosArm64()
    iosSimulatorArm64()

    cocoapods {
        framework {
            baseName = "Shared"
            isStatic = false
        }

        // Public pod from CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Custom version with operator
        pod("SnapKit") { version = "~> 5.6" }

        // Pod from private repo
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Local pod with path
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // Pod from git repo
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

Connecting pods is just part of the configuration. The plugin also allows you to export dependencies from other Kotlin modules to the iOS framework. The export(project(":core")) function specifies that all public APIs of the :core module should be accessible from the Objective-C header of the generated framework. This is necessary when shared Kotlin code uses classes from another module and they need to be accessible from Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Export modules to iOS framework
        export(project(":network"))
        export(project(":domain"))

        // Static or dynamic linking
        isStatic = true
    }

    // Pod required for exported modules
    pod("Moya") { version = "15.0" }
}

Build and Testing

After configuration, you need to run podInstall to generate the Podfile and install dependencies. Then the generated .xcworkspace is opened in Xcode, where the app can be built using the standard method. For CI/CD, make sure CocoaPods and Ruby are installed on the build machine. The plugin supports the --no-daemon flag for working in a CI environment.

// Install pods generates Podfile + xcworkspace
./gradlew :shared:podInstall

// Build debug framework for testing
./gradlew :shared:podBuildDebugFramework

// Full iOS build from command line
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) is an alternative dependency manager from Apple that is gaining popularity and gradually replacing CocoaPods in the iOS community. However, CocoaPods Plugin remains relevant for several reasons: SPM does not support dynamic frameworks in the KMM context, and integrating the Kotlin/Native framework through SPM requires additional setup. CocoaPods Plugin provides a more mature and documented integration path.

Comparison of CocoaPods Plugin and direct SPM integration shows that the former wins in automation, while the latter wins in native Apple support. CocoaPods Plugin automatically generates a Podfile, manages versions, and configures Xcode Build Phases. SPM requires manually connecting the Kotlin framework via Package.swift, which is harder to maintain for large KMM projects. JetBrains is working on SPM support for Kotlin/Native, but as of 2025, SPM integration remains experimental.

Common Problems and Solutions

When using CocoaPods Plugin, KMM developers encounter several typical problems. Pod version conflict is the most common issue, when two pods require different versions of the same dependency. The solution is to explicitly specify the version of the conflicting dependency via pod("Dependency") { version = "x.x" }. The second common case is version incompatibility, when a pod requires a newer iOS SDK than the KMM project minimum version.

Problems with .xcworkspace arise if you open .xcodeproj instead of .xcworkspace after configuring the plugin. The plugin warns about this in the podInstall logs. Another frequent error is the absence of CocoaPods on the development machine. The plugin checks for the pod command before running podInstall and outputs a clear error message. For CI/CD, install CocoaPods: gem install cocoapods.

// Resolve version conflict
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Explicitly resolve conflict
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Check CocoaPods installation via Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPods version: $result")
    }
}

Debugging podInstall

If podInstall fails, use the --info flag for detailed output: ./gradlew podInstall --info. The plugin logs each step: Podfile generation, pod install execution, Podfile.lock parsing. Most often, errors are related to network issues (CocoaPods Trunk unavailable) or incorrect Podfile syntax. In such cases, try running pod install manually in the project root to get a more detailed error message from CocoaPods.