IntelliJ IDEA IntelliJ Platform News Plugins

IntelliJ Platform 2025.3: What Plugin Developers Should Know

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.

No Immediate Upgrade Required

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.

Tip: Check compatibility locally by running the verifyPlugin Gradle task. This performs the same IntelliJ Plugin Verifier checks that are automatically run on JetBrains Marketplace when you upload plugin updates.

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.

Major Change: Unified Platform Distribution

What’s Changing?

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.

Starting with 2025.1, PyCharm has undergone the same unification. Learn more in the PyCharm Unified blog post.

Note: 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.

Key Implications for Plugin Developers

With the unified distribution:

• IntelliJ IDEA Community Edition (IC) builds for 2025.3 and later are no longer available. Trying to resolve artifacts using IC-2025.3, IC-253.x.y, or the intellijIdeaCommunity() dependency helper will cause an error.
• For version 2025.3 and future versions, you must target intellijIdea() as a platform artifact.
• When targeting PyCharm 2025.1 and above, use ⁠pycharm(version) instead of ⁠pycharmCommunity(version) and ⁠pycharmProfessional(version).
• The unified distribution retains the same IU product code as IntelliJ IDEA Ultimate.
• The difference between Community and Ultimate now depends on licensing and feature access, not separate IDE distributions. All IntelliJ IDEA Ultimate plugins are included in the distribution but are disabled if there is no active subscription.
• The Language Server Protocol (LSP) is available in a unified distribution and does not require a subscription.

Depending on Paid Functionality

If your plugin requires subscription-based features, you can explicitly depend on com.intellij.modules.ultimate. 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.

<idea-plugin>
<!-- ... -->
<depends>com.intellij.modules.platform</depends>
<depends>com.intellij.modules.ultimate</depends>
<!-- ... -->
</idea-plugin>

What Does This Mean for Your Users?

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.

The free tier now offers additional features:

• Basic database functions (schema viewing, SQL completion).
• Project wizards for Spring Boot, Ktor, and other frameworks.
• Basic syntax highlighting for frameworks.
• The Language Server Protocol (LSP) integration (previously only available in IntelliJ IDEA Ultimate).

Requirements

To work with version 2025.3, update the IntelliJ Platform Gradle Plugin to the latest version 2.10.4. Check the GitHub Releases page for updates or look for suggestions in logs when building the plugin.

plugins {
id("org.jetbrains.intellij.platform") version "2.10.4"
}

When targeting 2025.3 for development, you must use the new ⁠intellijIdea() dependency helper—whether your plugin targets IntelliJ IDEA specifically or all other IDEs based on the IntelliJ Platform.

// When targeting 2025.2 and earlier:
dependencies {
intellijPlatform {
intellijIdeaCommunity("2025.2")
// or intellijIdeaUltimate("2025.2")

bundledPlugin("com.intellij.java")
}
}

// When targeting 2025.3 and later:
dependencies {
intellijPlatform {
intellijIdea("2025.3")
bundledPlugin("com.intellij.java")
}
}

When targeting PyCharm specifically, use the pycharm() dependency:

// When targeting 2025.2 and earlier:
dependencies {
intellijPlatform {
pycharmCommunity("2024.3")
// or pycharmProfessional("2024.3")
}
}

// When targeting 2025.3 and later:
dependencies {
intellijPlatform {
pycharm("2025.3")
}
}

See the Step-by-Step Migration Guide below for detailed instructions on updating your plugin.

Open Source and Custom IDEs

For developers building custom IDEs or using the open source version:

• The open source code remains available on GitHub at JetBrains/intellij-community.
• GitHub Actions are now provided to simplify the process of building the IDE from source.
• Pre-built open source versions can be found on GitHub Releases.
• The open-source build utilizes the Community Edition (IC) product code and is compatible with all plugins that work with the Community Edition.

Custom IDEs, like Android Studio, continue to function as before.

Key API Changes in 2025.3

Module Extraction and Explicit Dependencies

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 bundledModule(moduleName):

• intellij.platform.collaborationTools.auth.base
• intellij.platform.collaborationTools.auth
• intellij.platform.scriptDebugger.backend
• intellij.platform.scriptDebugger.protocolReaderRuntime
• intellij.platform.scriptDebugger.ui
• intellij.platform.vcs.dvcs
• intellij.platform.vcs.log
• intellij.platform.vcs.log.graph

dependencies {
intellijPlatform {
intellijIdea("2025.3")
bundledModule("intellij.platform.vcs.dvcs")
bundledModule("intellij.platform.vcs.log")
}
}

IntelliLang Plugin Dependency Change

If your plugin relies on the org.intellij.intelliLang plugin, declare a dependency on the bundled module intellij.platform.langInjection:

// When targeting 2025.2 and earlier:
dependencies {
intellijPlatform {
intellijIdeaCommunity("2025.2")
bundledPlugin("org.intellij.intelliLang")
}
}

// When targeting 2025.3 and later:
dependencies {
intellijPlatform {
intellijIdea("2025.3")
bundledModule("intellij.platform.langInjection")
}
}

Storage Annotation Restriction

The @Storage annotation can no longer be used at the top level. It must only be used within @State.storages.

@Service
@State(name = "MySettings", storages = [Storage("MySettings.xml")])
class MySettings : PersistentStateComponent<MySettings> {

var myProperty = false

override fun getState() = this

override fun loadState(state: MySettings) = XmlSerializerUtil.copyBean(state, this)

companion object {
fun getInstance(): MySettings = service()
}
}

Why Explicit Dependencies Matter

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 determine product compatibility.

Understanding Dependencies: Gradle Build Script vs plugin.xml

Dependencies on plugins and modules defined in your Gradle build script, using the plugin(), bundledPlugin(), and bundledModule() 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 file. See the Plugin Dependencies documentation for details.

Example with plugin dependencies

In your build.gradle.kts:

dependencies {
intellijPlatform {
intellijIdea("2025.3")
bundledPlugin("com.intellij.java")
plugin("org.intellij.scala:2025.3.14")
}
}

In your plugin.xml:

<idea-plugin>
<!-- ... -->
<depends>com.intellij.modules.platform</depends>
<depends>com.intellij.java</depends>
<depends>org.intellij.scala</depends>
<!-- ... -->
</idea-plugin>

Example with plugin and bundled module dependencies

If your plugin depends on bundled modules, you must use the plugin model v2 dependencies definition, which requires the <dependencies> block with a clear separation between plugin and module dependencies.

In your build.gradle.kts:

dependencies {
intellijPlatform {
intellijIdea("2025.3")
bundledPlugin("com.intellij.java")
plugin("org.intellij.scala:2025.3.14")
bundledModule("intellij.platform.vcs.dvcs")
}
}

In your plugin.xml:

<idea-plugin>
<!-- ... -->
<dependencies>
<plugin id="com.intellij.modules.platform" />
<plugin id="com.intellij.java" />
<plugin id="org.intellij.scala" />
<module name="intellij.platform.vcs.dvcs" />
</dependencies>
<!-- ... -->
</idea-plugin>

This ensures that your plugin can compile with these dependencies during development and access them at runtime when users install it.

Step-by-Step Migration Guide

Update Your Gradle Plugin Version

Update the IntelliJ Platform Gradle Plugin to the latest version, currently 2.10.4. Check the GitHub Releases page for updates or look for suggestions in logs when building the plugin.

[org.jetbrains.intellij.platform] IntelliJ Platform Gradle Plugin is outdated: 2.10.0. Update `org.jetbrains.intellij.platform` to: 2.10.4

To update your setup to the latest version, simply increase the plugin version in the build.gradle.kts file or the ./gradle/libs.versions.toml if applicable.

plugins {
id("org.jetbrains.intellij.platform") version "2.10.4"
}

Testing Against 2025.3 Before Official Release

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.

In build.gradle.kts specify:

intellijPlatform {
pluginVerification {
ides {
recommended()
}
}
}

Next, run the verifyPlugin Gradle task to perform the verification and identify any potential issues that require attention.

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 runEap Gradle task and execute it immediately afterward.

val runEap by intellijPlatformTesting.runIde.registering {
type = IntelliJPlatformType.IntellijIdea
version = "253-EAP-SNAPSHOT"
useInstaller = false
}

Switching to 2025.3 for development

Important: 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:

Use a specific EAP release

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 intellijIdea("2025.3"). 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 or in a machine-readable JSON feed.

dependencies {
intellijPlatform {
intellijIdea("253.27864.23")
}
}

Use snapshot versions

JetBrains IDEs are also released as snapshots in the IntelliJ Platform Artifacts Repositories. 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.

dependencies {
intellijPlatform {
intellijIdea("253-EAP-SNAPSHOT") {
useInstaller = false
}
}
}

Once 2025.3 is officially released, simply use intellijIdea("2025.3"). For more details, see theTarget Versions documentation.

Frequently Asked Questions

Do I need to update my plugin immediately when 2025.3 is released?

No, plugins built for 2025.2 or older versions should still work with 2025.3.

What if my plugin only supports versions earlier than 2025.3?

No changes needed. The older syntax (intellijIdeaCommunity(version), intellijIdeaUltimate(version), pycharmCommunity(version), and pycharmProfessional(version)) still works for older versions.

Will my plugin work with both free-tier and paid subscription users?

Yes, using the intellijIdea("2025.3") makes your plugin work for all users regardless of subscription status.

Do I need to build multiple versions of my plugin for 2025.2 and 2025.3?

No. The platform type you specify in your build script is only used during plugin development. Your plugin.xml file contains the actual compatibility information through <depends> declarations and the since-build attribute. A single plugin build can work across multiple IDE versions.

Gradle fails with “Could not find idea:ideaIC:253.x.x”. What should I do?

This occurs because Community Edition builds are not available for versions 2025.3 and later. You have two options:

• Use an older version of IntelliJ IDEA Community for building, which will still make your plugin compatible with 2025.3.
• Upgrade the IntelliJ Platform Gradle Plugin to 2.10.4 and switch to intellijIdea(version).

If 2025.3 has not been released yet, you can use EAP by specifying a build number as the version.

Set the version to 253-EAP-SNAPSHOT and set useInstaller = false.

How do I know which modules to include explicitly in dependencies?

The IntelliJ Plugin Verifier will report missing dependencies. Refer to the Key API Changes in 2025.3 section above.

How can I test against 2025.3 before the official release?

Use specific EAP build numbers or snapshot versions, such as 253-EAP-SNAPSHOT, with useInstaller set to false. See Testing Against 2025.3 Before Official Release above.

What versioning scheme should I use if I need separate builds for different versions?

Use a SemVer-compatible scheme with suffixes, such as 1.2.3-251 for the 2025.1 version and 1.2.3-253 for the 2025.3 version. JetBrains Marketplace will automatically serve the correct version based on the user’s IDE version and your since-build and until-build attributes.

Conclusion

The IntelliJ Platform 2025.3 release introduces a unified IntelliJ IDEA distribution while maintaining strong backward compatibility. Plugins built for earlier IntelliJ Platform versions will still work with 2025.3, giving you time to migrate at your own pace.

When you’re ready to target 2025.3, update to IntelliJ Platform Gradle Plugin 2.10.4 or later and switch to the new intellijIdea() dependency helper. The platform APIs stay consistent across all license types, ensuring that your plugin works the same way for all users. Declare explicit dependencies on the modules you need, and use the verifyPlugin task to test compatibility before publishing.

Got questions? Contact us on the JetBrains Platform Forum. We’re dedicated to supporting a smooth transition for all plugin developers.

Subscribe to JetBrains Platform updates