--- description: Learn how to upgrade your Capacitor app to Capacitor 8 using the CLI, AI-powered Capawesome Skills, or a manual approach. title: How to Upgrade Your Capacitor App to Capacitor 8 - Capawesome image: https://capawesome.io/docs/assets/images/social/blog/how-to-upgrade-your-capacitor-app-to-capacitor-8.png --- [ Skip to content](#how-to-upgrade-your-capacitor-app-to-capacitor-8) [ 🎉 Introducing **Capawesome Platform** — one platform for Live Updates, Native Builds, App Store Publishing, and Insider SDKs.](https://capawesome.io) * [ Formbricks ](/docs/plugins/formbricks/) * [ Geocoder ](/docs/plugins/geocoder/) * [ Google Sign-In ](/docs/plugins/google-sign-in/) * [ libSQL ](/docs/plugins/libsql/) * [ Live Update ](/docs/plugins/live-update/) * [ Managed Configurations ](/docs/plugins/managed-configurations/) * [ Media Session ](/docs/plugins/media-session/) * [ ML Kit ](/docs/plugins/mlkit/) * [ NFC ](/docs/plugins/nfc/) * [ OAuth ](/docs/plugins/oauth/) * [ Pedometer ](/docs/plugins/pedometer/) * [ Photo Editor ](/docs/plugins/photo-editor/) * [ PostHog ](/docs/plugins/posthog/) * [ Printer ](/docs/plugins/printer/) * [ Purchases ](/docs/plugins/purchases/) * [ RealtimeKit ](/docs/plugins/realtimekit/) * [ Screen Orientation ](/docs/plugins/screen-orientation/) * [ Screenshot ](/docs/plugins/screenshot/) * [ Secure Preferences ](/docs/plugins/secure-preferences/) * [ Speech Recognition ](/docs/plugins/speech-recognition/) * [ Speech Synthesis ](/docs/plugins/speech-synthesis/) * [ Share Target ](/docs/plugins/share-target/) * [ Square Mobile Payments ](/docs/plugins/square-mobile-payments/) * [ SQLite ](/docs/plugins/sqlite/) * [ Superwall ](/docs/plugins/superwall/) * [ Torch ](/docs/plugins/torch/) * [ Wifi ](/docs/plugins/wifi/) * [ Zip ](/docs/plugins/zip/) * [ Cloud ](/docs/cloud/) * [ Live Updates ](/docs/cloud/live-updates/) * Advanced * Integrations * [ Native Builds ](/docs/cloud/native-builds/) * [ Configuration ](/docs/cloud/native-builds/configuration/) * [ Environments ](/docs/cloud/native-builds/environments/) * Guides * [ Sample Projects ](/docs/cloud/native-builds/sample-projects/) * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ Automations ](/docs/cloud/automations/) * [ Assist ](/docs/cloud/assist/) * Account * Organizations * [ Organization and User Management ](/docs/cloud/organizations/memberships/) * [ Single Sign-On (SSO) ](/docs/cloud/organizations/sso/) * [ Teams ](/docs/cloud/organizations/teams/) * [ Two-Factor Authentication ](/docs/cloud/organizations/two-factor-authentication/) * [ Integrations ](/docs/cloud/integrations/) * [ License Keys ](/docs/cloud/license-keys/) * [ Webhooks ](/docs/cloud/webhooks/) * [ Pricing ](https://capawesome.io/pricing/) * [ FAQ ](/docs/cloud/faq/) * [ Support ](/docs/cloud/support/) * [ Contributing ](/docs/contributing/) * [ LLMs ](/docs/llms/) * [ Insiders ](/docs/insiders/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/insiders/support/) * [ FAQ ](/docs/insiders/faq/) * [ Blog ](/blog/) * Categories * [ Upgrade Options ](#upgrade-options) * [ Which Approach Should You Choose? ](#which-approach-should-you-choose) * [ Try Capawesome Cloud ](#try-capawesome-cloud) * [ Conclusion ](#conclusion) # How to Upgrade Your Capacitor App to Capacitor 8[¶](#how-to-upgrade-your-capacitor-app-to-capacitor-8 "Permanent link") Capacitor 8 ships with Swift Package Manager as the default for iOS, targets Android SDK 36, and requires Node.js 22+. Whether you prefer an automated CLI migration, an AI-assisted upgrade, or full manual control, this guide walks you through all three approaches so you can pick the one that fits your project best. [ ![Build and deploy your Capacitor app with Capawesome Cloud](../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](/) ## Why Upgrade to Capacitor 8[¶](#why-upgrade-to-capacitor-8 "Permanent link") Before diving into the how, here's why the upgrade is worth it: * **Swift Package Manager by default**: New iOS projects use SPM instead of CocoaPods, aligning with Apple's direction for dependency management. CocoaPods [entered maintenance mode](https://blog.cocoapods.org/CocoaPods-Specs-Repo-Rate-Limiting/) in August 2024 and its Specs repository will become read-only in December 2026. * **Android SDK 36**: Targets the latest Android platform with updated Gradle tooling. * **Node.js 22+**: Requires the current LTS version, keeping your toolchain up to date. * **New System Bars plugin**: Replaces the removed `adjustMarginsForEdgeToEdge` config option with a proper core plugin for managing system bar insets via CSS `env` variables. * **Updated platform tooling**: Xcode 26+ and Android Studio Otter (2025.2.1+) are now required. ## What Changes at a Glance[¶](#what-changes-at-a-glance "Permanent link") Here's a summary of the most impactful breaking changes. For the full list, see the [official upgrade guide](https://capacitorjs.com/docs/updating/8-0). ### iOS[¶](#ios "Permanent link") * **SPM is the default** for new projects. To use CocoaPods instead, run `npx cap add ios --packagemanager CocoaPods`. * iOS deployment target raised to **15.0**. * Requires **Xcode 26.0+**. ### Android[¶](#android "Permanent link") * Minimum SDK raised to **24**, compile and target SDK updated to **36**. * Gradle wrapper updated to **8.14.3**, AGP to **8.13.0**. * `bridge_layout_main.xml` renamed to `capacitor_bridge_layout_main.xml`. * `density` must be added to `configChanges` in `AndroidManifest.xml`. * Updated `variables.gradle` values: `[](#%5F%5Fcodelineno-0-1)minSdkVersion = 24 [](#%5F%5Fcodelineno-0-2)compileSdkVersion = 36 [](#%5F%5Fcodelineno-0-3)targetSdkVersion = 36 ` ### Config[¶](#config "Permanent link") * `android.adjustMarginsForEdgeToEdge` has been removed. Use the new System Bars core plugin instead. ### Node.js[¶](#nodejs "Permanent link") * **Node.js 22** or greater is required. ## Upgrade Options[¶](#upgrade-options "Permanent link") There are three ways to upgrade — pick the one that best fits your project and workflow. ### Option 1: Upgrade Using the Capacitor CLI[¶](#option-1-upgrade-using-the-capacitor-cli "Permanent link") The fastest way to upgrade is the built-in `migrate` command. It updates your dependencies, adjusts platform configuration files, and handles most of the heavy lifting automatically. `[](#%5F%5Fcodelineno-1-1)npm i -D @capacitor/cli@latest [](#%5F%5Fcodelineno-1-2)npx cap migrate ` The CLI will walk you through the migration interactively — updating `package.json` dependencies, modifying native project files, and prompting you where manual intervention is needed. This works well for most projects. However, if your app has significant native customizations (custom build scripts, manual Gradle modifications, or non-standard project structures), you may need to handle some steps manually after the migration. Check the CLI output carefully for any warnings or skipped steps. ### Option 2: Upgrade Using Capawesome Skills[¶](#option-2-upgrade-using-capawesome-skills "Permanent link") [Capawesome Skills](https://github.com/capawesome-team/skills) are AI agent tools designed to automate development tasks for Capacitor projects. They work with AI coding assistants like Claude Code, Cursor, or GitHub Copilot and provide step-by-step upgrade instructions that are optimized for machine-actionable execution. First, add the skills to your project: `[](#%5F%5Fcodelineno-2-1)npx skills add capawesome-team/skills ` Then, use the following prompt with your AI coding assistant: `` [](#%5F%5Fcodelineno-3-1)Use the `capacitor-app-upgrades` skill from `capawesome-team/skills` [](#%5F%5Fcodelineno-3-2)to help me upgrade my Capacitor app to Capacitor 8. `` The skill will attempt the automated upgrade first and fall back to manual steps where needed. It covers both the core Capacitor upgrade and the configuration of 160+ Capacitor plugins, making it a good choice for projects with many dependencies. ### Option 3: Upgrade Manually[¶](#option-3-upgrade-manually "Permanent link") If you prefer full control over every change, you can follow the [official Capacitor 8 upgrade guide](https://capacitorjs.com/docs/updating/8-0) step by step. Here's a condensed overview of the key steps: 1. Update Node.js to version 22+. 2. Install the latest Capacitor packages: `[](#%5F%5Fcodelineno-4-1)npm i @capacitor/cli@latest @capacitor/core@latest @capacitor/ios@latest @capacitor/android@latest ` 1. **iOS**: Update Xcode to 26.0+, set the deployment target to 15.0, and update the `Podfile` platform accordingly. 2. **Android**: Update Android Studio to Otter (2025.2.1+), run the AGP Upgrade Assistant, update `variables.gradle` with the new SDK and dependency versions, update the Gradle wrapper to 8.14.3, and add `density` to `configChanges` in `AndroidManifest.xml`. 3. Update all official and third-party Capacitor plugins to their Capacitor 8–compatible versions. 4. Replace any usage of `adjustMarginsForEdgeToEdge` with the new System Bars core plugin. This approach takes more effort but gives you the most visibility into exactly what changes in your project. ## Which Approach Should You Choose?[¶](#which-approach-should-you-choose "Permanent link") | Approach | Best for | Trade-off | | --------------------- | --------------------------------------------------- | -------------------------------------------------------- | | **Capacitor CLI** | Most projects with standard setups | Fast, but may skip steps in heavily customized projects | | **Capawesome Skills** | Projects with many plugins or native customizations | Handles edge cases well, requires an AI coding assistant | | **Manual** | Teams that want full control over every change | Most effort, but complete visibility | For most teams, starting with the **Capacitor CLI** is the right call. If you run into issues or have a complex project with many plugins, **Capawesome Skills** can help fill in the gaps. The **manual** approach is there when you need it, but it's rarely necessary to do everything by hand. ## Try Capawesome Cloud[¶](#try-capawesome-cloud "Permanent link") Building and deploying Capacitor apps is easier with [Capawesome Cloud](/). Get cloud-based native builds, over-the-air live updates, and automated app store publishing — all in one platform. [Try Capawesome Cloud Free](/) ## Conclusion[¶](#conclusion "Permanent link") Capacitor 8 brings meaningful platform updates — SPM as the iOS default, Android SDK 36 targeting, and a cleaner approach to system bar insets. Upgrading doesn't have to be painful: the CLI handles most of the work, Capawesome Skills can assist with complex projects, and the manual route is always available as a fallback. If you're upgrading a Capacitor plugin, check out [How to Upgrade Your Capacitor Plugin to Capacitor 8](/blog/how-to-upgrade-your-capacitor-plugin-to-capacitor-8/) for a full walkthrough of the plugin-level migration. If you're also using Capawesome plugins, check out [Updating to Capacitor 8.0](/blog/updating-to-capacitor-8/) for a breakdown of plugin-specific breaking changes. If you have questions, join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW). To stay up to date with the latest news, subscribe to the [Capawesome newsletter](/newsletter/). May 7, 2026 Back to top