As we approach the release of IntelliJ IDEA 2025.3, we would like to share key information about changes that may impact your plugin development process. This post addresses common questions from the developer community and provides guidance on maintaining compatibility with the latest IntelliJ Platform versions.<\/p>\n\n\n\n
If you built your plugin against the IntelliJ Platform 2025.2 or earlier, it should remain compatible with 2025.3. You don’t need to rush to update right away.<\/p>\n\n\n\n
Tip:<\/strong> Check compatibility locally by running the The IntelliJ Platform maintains strong backward compatibility, which generally preserves between minor versions. It means you can take your time testing and migrating your plugins.<\/p>\n\n\n\n Starting with version 2025.3, IntelliJ IDEA Community and Ultimate will be delivered as a unified platform. This marks a significant architectural change that makes plugin development and distribution easier. Read the full announcement: IntelliJ IDEA Moves to the Unified Distribution<\/a>.<\/p>\n\n\n\n Starting with 2025.1, PyCharm has undergone the same unification. Learn more in the PyCharm Unified blog post<\/a>.<\/p>\n\n\n\n Note:<\/strong> These updates only affect plugins targeting IntelliJ IDEA 2025.3 and later. If your plugin still uses the IntelliJ Platform in version 2025.2 or earlier, no changes are needed at this time. References to IntelliJ IDEA Ultimate or Community for older versions continue working.<\/p>\n\n\n\n With the unified distribution:<\/p>\n\n\n\n If your plugin requires subscription-based features, you can explicitly depend on Users upgrading from IntelliJ IDEA Community 2025.2 will be smoothly transitioned to the unified IntelliJ IDEA 2025.3 as part of a regular version update. All plugins will continue working. <\/p>\n\n\n\n The free tier now offers additional features:<\/p>\n\n\n\n To work with version 2025.3, update the IntelliJ Platform Gradle Plugin to the latest version 2.10.4<\/strong>. Check the GitHub Releases<\/a> page for updates or look for suggestions in logs when building the plugin.<\/p>\n\n\n\n When targeting 2025.3 for development, you must use the new When targeting PyCharm specifically, use the See the Step-by-Step Migration Guide<\/em> below for detailed instructions on updating your plugin.<\/p>\n\n\n\n For developers building custom IDEs or using the open source version:<\/p>\n\n\n\n Custom IDEs, like Android Studio, continue to function as before.<\/p>\n\n\n\n Several modules have been separated from the core plugin into their own modules, each with its own individual classloader. While this does not affect binary compatibility, it is advisable to explicitly depend on the modules you need using If your plugin relies on the The Declaring explicit dependencies on the plugins and modules your plugin uses is a best practice. It makes your plugin’s requirements clear to both the platform and other developers, ensures proper dependency loading order, and helps JetBrains Marketplace<\/a> determine product compatibility.<\/p>\n\n\n\n Dependencies on plugins and modules defined in your Gradle build script, using the In your In your If your plugin depends on bundled modules, you must use the plugin model v2 dependencies definition, which requires the In your In your This ensures that your plugin can compile with these dependencies during development and access them at runtime when users install it.<\/p>\n\n\n\n Update the IntelliJ Platform Gradle Plugin to the latest version, currently 2.10.4. Check the GitHub Releases<\/a> page for updates or look for suggestions in logs when building the plugin.<\/p>\n\n\n\n To update your setup to the latest version, simply increase the plugin version in the Even if your plugin is designed for older versions of the IntelliJ Platform, it can still be used in future releases. To ensure compatibility with newer IDEs than the SDK you use, utilize the IntelliJ Plugin Verifier tool to check binary compatibility against other IntelliJ Platform versions.<\/p>\n\n\n\n In Next, run the It is also possible to manually run a specific IDE with a different version than the one set for development, with your plugin loaded. To do this, register a new Important:<\/strong> The installer for IntelliJ IDEA 2025.3 will only be available once 2025.3 is officially released. Until then, if you want to test your plugin against 2025.3 early, you have two options:<\/p>\n\n\n\n All published JetBrains IDEs available for download are ready for use by all users and should also be used for plugin development to reflect our customers’ needs. To do this, you can simply add the IntelliJ Platform dependency using JetBrains IDEs are also released as snapshots in the IntelliJ Platform Artifacts Repositories<\/a>. To switch to these intermediate releases, you need to opt out of the installer artifacts and use a version specific to the IntelliJ Snapshots Maven Repository<\/a>.<\/p>\n\n\n\nverifyPlugin<\/code><\/a> Gradle task. This performs the same IntelliJ Plugin Verifier checks that are automatically run on JetBrains Marketplace when you upload plugin updates.<\/p>\n\n\n\nMajor Change: Unified Platform Distribution<\/h1>\n\n\n\n
What’s Changing?<\/h2>\n\n\n\n
Key Implications for Plugin Developers<\/h2>\n\n\n\n
\n
IC<\/code>) builds for 2025.3 and later are no longer available. Trying to resolve artifacts using IC-2025.3<\/code>, IC-253.x.y<\/code>, or the intellijIdeaCommunity()<\/code> dependency helper will cause an error.<\/li>\n\n\n\nintellijIdea()<\/code> as a platform artifact.<\/li>\n\n\n\n\u2060pycharm(version)<\/code> instead of \u2060pycharmCommunity(version)<\/code> and \u2060pycharmProfessional(version)<\/code>.<\/li>\n\n\n\nIU<\/code> product code as IntelliJ IDEA Ultimate.<\/li>\n\n\n\nDepending on Paid Functionality<\/h2>\n\n\n\n
com.intellij.modules.ultimate<\/code>. This module represents the licensing mechanism; when a user doesn’t have an active subscription, this module and all plugins that depend on it are disabled.<\/p>\n\n\n\n<idea-plugin>\n\u00a0\u00a0\u00a0\u00a0<!-- ... -->\n\u00a0\u00a0\u00a0\u00a0<depends>com.intellij.modules.platform<\/depends>\n\u00a0\u00a0\u00a0\u00a0<depends>com.intellij.modules.ultimate<\/depends>\n\u00a0\u00a0\u00a0\u00a0<!-- ... -->\n<\/idea-plugin><\/pre>\n\n\n\n
What Does This Mean for Your Users?<\/h2>\n\n\n\n
\n
Requirements<\/h2>\n\n\n\n
plugins {\n id(\"org.jetbrains.intellij.platform\") version \"2.10.4\"\n}<\/pre>\n\n\n\n\u2060intellijIdea()<\/code> dependency helper\u2014whether your plugin targets IntelliJ IDEA specifically or all other IDEs based on the IntelliJ Platform.<\/p>\n\n\n\n\/\/ When targeting 2025.2 and earlier:\ndependencies {\n intellijPlatform {\n intellijIdeaCommunity(\"2025.2\")\n \/\/ or intellijIdeaUltimate(\"2025.2\")\n\n bundledPlugin(\"com.intellij.java\")\n }\n}\n\n\/\/ When targeting 2025.3 and later:\ndependencies {\n intellijPlatform {\n intellijIdea(\"2025.3\")\n bundledPlugin(\"com.intellij.java\")\n }\n}<\/pre>\n\n\n\npycharm()<\/code> dependency:<\/p>\n\n\n\n\/\/ When targeting 2025.2 and earlier:\ndependencies {\n intellijPlatform {\n pycharmCommunity(\"2024.3\")\n \/\/ or pycharmProfessional(\"2024.3\")\n }\n}\n\n\/\/ When targeting 2025.3 and later:\ndependencies {\n intellijPlatform {\n pycharm(\"2025.3\")\n }\n}<\/pre>\n\n\n\nOpen Source and Custom IDEs<\/h1>\n\n\n\n
\n
IC<\/code>) product code and is compatible with all plugins that work with the Community Edition.<\/li>\n<\/ul>\n\n\n\nKey API Changes in 2025.3<\/h1>\n\n\n\n
Module Extraction and Explicit Dependencies<\/h2>\n\n\n\n
bundledModule(moduleName)<\/code>:<\/p>\n\n\n\n\n
intellij.platform.collaborationTools.auth.base<\/code><\/li>\n\n\n\nintellij.platform.collaborationTools.auth<\/code><\/li>\n\n\n\nintellij.platform.scriptDebugger.backend<\/code><\/li>\n\n\n\nintellij.platform.scriptDebugger.protocolReaderRuntime<\/code><\/li>\n\n\n\nintellij.platform.scriptDebugger.ui<\/code><\/li>\n\n\n\nintellij.platform.vcs.dvcs<\/code><\/li>\n\n\n\nintellij.platform.vcs.log<\/code><\/li>\n\n\n\nintellij.platform.vcs.log.graph<\/code><\/li>\n<\/ul>\n\n\n\ndependencies {\n intellijPlatform {\n intellijIdea(\"2025.3\")\n bundledModule(\"intellij.platform.vcs.dvcs\")\n bundledModule(\"intellij.platform.vcs.log\")\n }\n}<\/pre>\n\n\n\nIntelliLang Plugin Dependency Change<\/h2>\n\n\n\n
org.intellij.intelliLang<\/code> plugin, declare a dependency on the bundled module intellij.platform.langInjection<\/code>:<\/p>\n\n\n\n\/\/ When targeting 2025.2 and earlier:\ndependencies {\n intellijPlatform {\n intellijIdeaCommunity(\"2025.2\")\n bundledPlugin(\"org.intellij.intelliLang\")\n }\n}\n\n\/\/ When targeting 2025.3 and later:\ndependencies {\n intellijPlatform {\n intellijIdea(\"2025.3\")\n bundledModule(\"intellij.platform.langInjection\")\n }\n}<\/pre>\n\n\n\nStorage Annotation Restriction<\/h2>\n\n\n\n
@Storage<\/code> annotation can no longer be used at the top level. It must only be used within @State.storages<\/code>.<\/p>\n\n\n\n@Service\n@State(name = \"MySettings\", storages = [Storage(\"MySettings.xml\")])\nclass MySettings : PersistentStateComponent<MySettings> {\n\n var myProperty = false\n\n override fun getState() = this\n\n override fun loadState(state: MySettings) = XmlSerializerUtil.copyBean(state, this)\n\n companion object {\n fun getInstance(): MySettings = service()\n }\n}<\/pre>\n\n\n\nWhy Explicit Dependencies Matter<\/h2>\n\n\n\n
Understanding Dependencies: Gradle Build Script vs plugin.xml<\/h3>\n\n\n\n
plugin()<\/code>, bundledPlugin()<\/code>, and bundledModule()<\/code> dependency helpers, interact with the compilation classpath to ensure they are available during plugin development. However, to make them available at runtime for your plugin, it’s also required to define them in your plugin.xml<\/code> file. See the Plugin Dependencies documentation<\/a> for details.<\/p>\n\n\n\nExample with plugin dependencies<\/h4>\n\n\n\n
build.gradle.kts<\/code>:<\/p>\n\n\n\ndependencies {\n intellijPlatform {\n intellijIdea(\"2025.3\")\n bundledPlugin(\"com.intellij.java\")\n plugin(\"org.intellij.scala:2025.3.14\")\n }\n}<\/pre>\n\n\n\nplugin.xml<\/code>:<\/p>\n\n\n\n<idea-plugin>\n <!-- ... -->\n <depends>com.intellij.modules.platform<\/depends>\n <depends>com.intellij.java<\/depends>\n <depends>org.intellij.scala<\/depends>\n <!-- ... -->\n<\/idea-plugin><\/pre>\n\n\n\n
Example with plugin and bundled module dependencies<\/h4>\n\n\n\n
<dependencies><\/code> block with a clear separation between plugin and module dependencies.<\/p>\n\n\n\nbuild.gradle.kts<\/code>:<\/p>\n\n\n\ndependencies {\n intellijPlatform {\n intellijIdea(\"2025.3\")\n bundledPlugin(\"com.intellij.java\")\n plugin(\"org.intellij.scala:2025.3.14\")\n bundledModule(\"intellij.platform.vcs.dvcs\")\n }\n}<\/pre>\n\n\n\nplugin.xml<\/code>:<\/p>\n\n\n\n<idea-plugin>\n <!-- ... -->\n <dependencies>\n <plugin id=\"com.intellij.modules.platform\" \/>\n <plugin id=\"com.intellij.java\" \/>\n <plugin id=\"org.intellij.scala\" \/>\n <module name=\"intellij.platform.vcs.dvcs\" \/>\n <\/dependencies>\n <!-- ... -->\n<\/idea-plugin><\/pre>\n\n\n\n
Step-by-Step Migration Guide<\/h1>\n\n\n\n
Update Your Gradle Plugin Version<\/h2>\n\n\n\n
[org.jetbrains.intellij.platform] IntelliJ Platform Gradle Plugin is outdated: 2.10.0. Update `org.jetbrains.intellij.platform` to: 2.10.4<\/pre>\n\n\n\n
build.gradle.kts<\/code> file or the .\/gradle\/libs.versions.toml<\/code> if applicable.<\/p>\n\n\n\nplugins {\n id(\"org.jetbrains.intellij.platform\") version \"2.10.4\"\n}<\/pre>\n\n\n\nTesting Against 2025.3 Before Official Release<\/h2>\n\n\n\n
build.gradle.kts<\/code> specify:<\/p>\n\n\n\nintellijPlatform {\n pluginVerification {\n ides {\n recommended()\n }\n }\n}<\/pre>\n\n\n\nverifyPlugin<\/code> Gradle task to perform the verification and identify any potential issues that require attention.<\/p>\n\n\n\nrunEap<\/code> Gradle task and execute it immediately afterward.<\/p>\n\n\n\nval runEap by intellijPlatformTesting.runIde.registering {\n type = IntelliJPlatformType.IntellijIdea\n version = \"253-EAP-SNAPSHOT\"\n useInstaller = false\n}<\/pre>\n\n\n\nSwitching to 2025.3 for development<\/h2>\n\n\n\n
Use a specific EAP release<\/h3>\n\n\n\n
intellijIdea(\"2025.3\")<\/code>. However, if such a version is not yet available, you can refer to early access releases, which include their build numbers, available on the IntelliJ IDEA EAP download page<\/a> or in a machine-readable JSON feed<\/a>.<\/p>\n\n\n\ndependencies {\n intellijPlatform {\n intellijIdea(\"253.27864.23\")\n }\n}<\/pre>\n\n\n\nUse snapshot versions<\/h3>\n\n\n\n
dependencies {\n intellijPlatform {\n intellijIdea(\"253-EAP-SNAPSHOT\") {\n useInstaller = false\n }\n }\n}<\/pre>\n\n\n\n