Skip to main content
Version: v9

Updating from Capacitor 8 to Capacitor 9

In this guide, you'll find steps to update your project to the current Capacitor 9 version as well as a list of breaking changes for our official plugins.

note

This guide covers app-level changes. If you maintain a Capacitor plugin, see the "Updating plugins to 9.0" guide instead.

Cordova support is now optional​

Capacitor's Cordova compatibility layer is now only included in your app when your project actually has a Cordova plugin installed. Previously, the native Cordova runtime (the capacitor-cordova-android Gradle module and plugins module on Android, and the CapacitorCordova CocoaPods pod / SPM product on iOS) was always bundled into every app, whether or not it used any Cordova plugins.

Running npx cap sync (or update) now detects whether any installed plugin is a Cordova plugin and only wires in the Cordova runtime when one is found. If your project has no Cordova plugins, you'll notice:

  • On Android, the generated settings.gradle and app build.gradle no longer include the capacitor-cordova-android / capacitor-cordova-android-plugins modules.
  • On iOS, CapacitorCordova is no longer added to your Podfile or Package.swift.

There is currently no configuration option to force-include the Cordova runtime when no Cordova plugin is present. If your app's native code (or a plugin you maintain) directly references symbols from Capacitor's Cordova compatibility layer — for example com.getcapacitor.cordova.CordovaPlugin on Android, or anything from the CapacitorCordova pod/product on iOS — without having an actual Cordova plugin installed, those references will fail to resolve after upgrading. Add a Cordova plugin dependency (even a trivial one) if you need the layer present, or remove the direct reference.

Breaking changes in @capacitor/cli​

cap run's separate live-reload flags (--live-reload/-l, --host, --port, --https) have been merged into a single --url flag. Instead of:

npx cap run android -l --host 192.168.1.181 --port 5173

pass the full URL your dev server printed (Vite, webpack, etc.) directly:

npx cap run android --url http://192.168.1.181:5173

Breaking changes in @capacitor/android​

minSdkVersion is now 26 (Android 8.0), and compileSdkVersion/targetSdkVersion are now 37 (Android 17).

AGP 9 no longer ships proguard-android.txt — any build.gradle that still references it fails at Gradle configuration time, even with minifyEnabled false:

// Before — hard build error on AGP 9
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
// After
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'

androidx.core:core 1.19.0 merges every extension function previously shipped in core-ktx into core itself, turning core-ktx into an empty compatibility artifact. If your app (or an old/community plugin it depends on) still explicitly pins core-ktx to a version older than 1.19.0, you may hit a duplicate class error at build time; remove the explicit core-ktx version override.

AGP 9 also bundles the Kotlin Gradle Plugin natively and removes the jcenter() repository helper entirely. These are unlikely to affect your app directly, but can break the build if you (or a legacy/community plugin) still apply Kotlin standalone or reference jcenter() — see Update Kotlin and remove jcenter() below.

Breaking changes in @capacitor/ios​

The minimum iOS deployment target is now 16.0 (previously 15.0).

If you're updating from Capacitor 8.4 or earlier, you also need to adopt the iOS UIScene lifecycle, which Xcode 27 requires — see Updating to 8.5 for the full steps. Apps already on 8.5 have nothing further to do here.

New iOS projects created with npx cap add ios now use @main instead of the deprecated @UIApplicationMain attribute on AppDelegate. This doesn't change existing apps automatically, but Swift 6 (bundled with Xcode 27) rejects the deprecated attribute — if your AppDelegate.swift still declares @UIApplicationMain, replace it with @main.

NodeJS 24+​

Capacitor 9 requires NodeJS 24 or greater. (Latest LTS version is recommended.)

Using the CLI to Migrate​

Capacitor 9 hasn't reached general availability yet, so install the next version of the Capacitor CLI to your project (once 9.0.0 is generally available, use @latest instead):

npm i -D @capacitor/cli@next

Once installed, simply run the following to have the CLI handle the migration for you.

npx cap migrate

If any of the steps for the migration are not able to be completed, additional information will be made available in the output in the terminal. The steps for doing the migration manually are listed out below.

iOS​

The following guide describes how to upgrade your Capacitor 8 iOS project to Capacitor 9.

Upgrade Xcode​

Capacitor 9 requires Xcode 27 or newer.

Raise iOS Deployment Target​

Do the following for your Xcode project: select the Project within the project editor and open the Build Settings tab. Under the Deployment section, change iOS Deployment Target to iOS 16.0. Repeat the same steps for any app Targets.

Then, if the project is using CocoaPods, open ios/App/Podfile and update the iOS version to 16.0:

platform :ios, '16.0'
note

CocoaPods Trunk is expected to become read-only later in 2026. If you haven't already, consider migrating your app to SPM, which is the default for new Capacitor projects.

Android​

The following guide describes how to upgrade your Capacitor 8 Android project to Capacitor 9.

Upgrade Android Studio​

Capacitor 9 requires Android Studio 2025.3.3 or newer.

Once it's updated, Android Studio can assist with some of the updates related to gradle. To start, run Tools -> AGP Upgrade Assistant and choose 9.2.1 as the version to update on dropdown. Then click Run selected steps.

APG Upgrade Assistant

Update Android Project Variables​

In your variables.gradle file, update your values to the following new minimums

minSdkVersion = 26
compileSdkVersion = 37
targetSdkVersion = 37
androidxActivityVersion = '1.13.0'
androidxAppCompatVersion = '1.7.1'
androidxCoordinatorLayoutVersion = '1.3.0'
androidxCoreVersion = '1.19.0'
androidxFragmentVersion = '1.8.9'
coreSplashScreenVersion = '1.2.0'
androidxWebkitVersion = '1.16.0'
junitVersion = '4.13.2'
androidxJunitVersion = '1.3.0'
androidxEspressoCoreVersion = '3.7.0'
cordovaAndroidVersion = '15.0.0'

Rename the default ProGuard file​

AGP 9 removed proguard-android.txt. In your app/build.gradle, replace it with proguard-android-optimize.txt, which also enables ProGuard optimizations:

buildTypes {
    release {
        minifyEnabled false
-       proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+       proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}

Update Kotlin and remove jcenter()​

AGP 9 bundles the Kotlin Gradle Plugin natively (Kotlin 2.2.10) instead of requiring it to be applied as a separate plugin. If your build.gradle still applies kotlin-android directly or declares a standalone kotlin-stdlib/kotlin-gradle-plugin dependency, remove them — keeping them alongside AGP 9's built-in Kotlin causes a duplicate-plugin build failure:

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:9.2.1'
-       classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.10"
    }
}
-apply plugin: 'kotlin-android'

dependencies {
-   implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.10"
}

Gradle 9 also fully removes the jcenter() repository helper (redirected to Maven Central since 2024). Any build.gradle that still calls it fails at Gradle configuration time:

repositories {
    google()
-   jcenter()
+   mavenCentral()
}

Update google services plugin​

# build.gradle

    dependencies {
        classpath 'com.android.tools.build:gradle:9.2.1'
-       classpath 'com.google.gms:google-services:4.4.4'
+       classpath 'com.google.gms:google-services:4.5.0'

Update gradle plugin to 9.2.1​

# build.gradle

    dependencies {
-       classpath 'com.android.tools.build:gradle:8.13.0'
+       classpath 'com.android.tools.build:gradle:9.2.1'

Update gradle wrapper to 9.5.1​

# gradle-wrapper.properties

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
- distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip
+ distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.1-all.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Plugins​

Plugins have been updated to version 9.0.0, make sure to update them to use latest version.

The following plugin functionality has been modified or removed. Update your code accordingly.

Action Sheet​

  • androidxMaterialVersion variable has been updated to 1.14.0.

Browser​

  • androidxBrowserVersion variable has been updated to 1.10.0.

Barcode Scanner​

  • Native Android dependencies have been updated to their latest versions.

Camera​

  • Native Android dependencies have been updated to their latest versions.

Geolocation​

  • Native Android dependencies have been updated to their latest versions.

Google Maps​

  • kotlinxCoroutinesVersion variable has been updated to 1.11.0.
  • googleMapsPlayServicesVersion variable has been updated to 20.0.0.
  • googleMapsUtilsVersion variable has been updated to 5.0.0.
  • googleMapsKtxVersion and googleMapsUtilsKtxVersion variables have been updated to 6.0.1.

InAppBrowser​

  • Native Android dependencies have been updated to their latest versions.

Push Notifications​

The deprecated alert presentation option is no longer supported on iOS. Use banner and/or list instead.

Splash Screen​

The default value of launchFadeOutDuration on Android has changed from 200 to 0, since the previous default could block UI changes made immediately after SplashScreen.hide(). If your app relies on the previous 200ms fade-out animation, set launchFadeOutDuration: 200 explicitly in your Capacitor config.

Contents

Edit this page