Plugin Configuration File
The plugin.xml configuration file contains all the information about the plugin, which is displayed in the plugins settings dialog, and all registered extensions, actions, listeners, etc. Sections below describe all the elements in detail.
The example plugin.xml files can be found in the IntelliJ SDK Docs Code Samples repository.
Additional Plugin Configuration Files
A plugin can contain additional configuration files beside the main plugin.xml. They have the same format, and they are included with the config-file
attribute of <depends>
elements specifying plugin dependencies. However, some elements and attributes required in plugin.xml are ignored in additional configuration files. If the requirements differ, the documentation below will state it explicitly. One use case for additional configuration files is when a plugin provides optional features that are only available in some IDEs and require certain modules.
Useful Resources
Please make sure to follow the guidelines from Plugin Overview page for an optimal presentation of your plugin on JetBrains Marketplace. The Busy Plugin Developers. Episode 2 discusses 5 tips for optimizing JetBrains Marketplace plugin page in more detail.
See also Marketing about widgets and badges.
Configuration Structure Overview
Deprecated elements are omitted in the list above.
idea-plugin
The plugin.xml file root element.
- Required
yes
- Attributes
url
(optional; ignored in additional configuration)The link to the plugin homepage displayed on the plugin page in the JetBrains Marketplace.
require-restart
(optional)The boolean value determining whether the plugin installation, update, or uninstallation requires the IDE restart (see Dynamic Plugins for details).
Default value:
false
.
- Children
Deprecated:
id
A unique identifier of the plugin. It should be a fully qualified name similar to Java packages and must not collide with the ID of existing plugins. The ID is a technical value used to identify the plugin in the IDE and JetBrains Marketplace.
The identifier value cannot be changed between the plugin versions.
- Required
no; ignored in additional config file
It is highly recommended to set in plugin.xml file.
The element can be skipped in the source plugin.xml file if the Gradle
patchPluginXml
task is enabled and configured.- Default value
Value of the
<name>
element.- Example
- <id>com.example.myframeworksupport</id>
name
The user-visible plugin display name (Title Case).
Reference: JetBrains Marketplace: Plugin Name
- Required
yes; ignored in additional config file
- Example
- <name>My Framework Support</name>
version
The plugin version displayed in the Plugins settings dialog and in the JetBrains Marketplace plugin page. Plugins uploaded to the JetBrains Marketplace must follow semantic versioning.
Reference: JetBrains Marketplace: Semantic Versioning
- Required
yes; ignored in additional config file
The element can be skipped in the source plugin.xml file if the Gradle
patchPluginXml
task is enabled and configured.- Example
- <version>1.3.18</version>
product-descriptor
Paid or Freemium plugin descriptor.
Reference: JetBrains Marketplace: How to add required parameters for paid plugins
- Required
only for paid or freemium plugins; ignored in additional config file
Do not add
<product-descriptor>
element in a free plugin.- Attributes
code
(required)The plugin product code used in the JetBrains Sales System. The code must be agreed with JetBrains in advance and follow the requirements.
release-date
(required)Date of the major version release in the
YYYYMMDD
format.release-version
(required)A major version in a special number format.
optional
(optional)The boolean value determining whether the plugin is a Freemium plugin.
Default value:
false
.
idea-version
The plugin's range of compatible IntelliJ-based IDE versions.
Reference: Build Number Ranges
- Required
yes; ignored in additional config file
The element can be skipped in the source plugin.xml file if the Gradle
patchPluginXml
task is enabled and configured.- Attributes
since-build
(required)The lowest IDE version compatible with the plugin.
until-build
(optional)The highest IDE version compatible with the plugin. Undefined value declares compatibility with all the IDEs since the version specified by the
since-build
(also with the future builds what may cause incompatibility errors).
- Examples
Compatibility with a specific build number (2021.3.3) and higher versions:
<idea-version since-build="213.7172.25"/>Compatibility with versions from any of
213
branches to any of221
branches:<idea-version since-build="213" until-build="221.*"/>
vendor
The vendor name or organization ID (if created) in the Plugins settings dialog and in the JetBrains Marketplace plugin page.
Reference: JetBrains Marketplace: Contacts and Resources
- Required
yes; ignored in additional config file
- Attributes
url
(optional)The link to the vendor's homepage.
email
(optional)The vendor's email address.
- Examples
Personal vendor with an email address provided:
<vendor email="joe@example.com">Joe Doe</vendor>Organizational vendor with a website URL and email address provided:
<vendor url="https://mycompany.example.com" email="contact@example.com"> My Company </vendor>
description
The plugin description displayed on the JetBrains Marketplace plugin page and in the Plugins settings dialog.
Simple HTML elements, like text formatting, paragraphs, lists, etc., are allowed and must be wrapped into <![CDATA[
... ]]>
section.
Reference: JetBrains Marketplace: Plugin Description
- Required
yes; ignored in additional config file
The element can be skipped in the source plugin.xml file if the Gradle
patchPluginXml
task is enabled and configured.- Example
- <description><![CDATA[ Provides support for My Framework. The support includes: <ul> <li>code completion</li> <li>references</li> </ul> For more information visit the <a href="https://example.com">project site</a>. ]]></description>
change-notes
A short summary of new features, bugfixes, and changes provided with the latest plugin version. Change notes are displayed on the JetBrains Marketplace plugin page and in the Plugins settings dialog.
Simple HTML elements, like text formatting, paragraphs, lists, etc., are allowed and must be wrapped into <![CDATA[
... ]]>
section.
Reference: JetBrains Marketplace: Change Notes
- Required
no; ignored in additional config file
The element can be skipped in the source plugin.xml file if the Gradle
patchPluginXml
task is enabled and configured.- Example
- <change-notes><![CDATA[ <h2>New Features</h2> <ul> <li>Feature 1</li> <li>Feature 2</li> </ul> <h2>Bug Fixes</h2> <ul> <li>Fixed issue 1</li> <li>Fixed issue 2</li> </ul> ]]></change-notes>
depends
Specifies a dependency on another plugin or a module of an IntelliJ Platform-based product. A single <idea-plugin>
element can contain multiple <depends>
elements.
References:
- Required
no; in most cases dependency on the platform module is needed
- Attributes
optional
(optional)Boolean value defining whether the dependency is optional to load the plugin in the IDE. If the dependency plugin is not installed in the current IDE, and
optional
is:true
- the plugin will be loadedfalse
(default) - the plugin will not be loaded
config-file
(optional)Relative path to an additional configuration file, loaded only if the dependency plugin is installed in the current IDE.
- Examples
Required plugin dependency:
<depends>com.example.dependencypluginid</depends>Required dependency on the IntelliJ IDEA Java Module:
<depends>com.intellij.modules.java</depends>Optional plugin dependency:
<depends optional="true"> com.example.dependencypluginid </depends>Required module dependency with additional configuration:
<depends config-file="myPluginId-withJava.xml"> com.intellij.modules.java </depends>Optional module dependency with additional configuration:
<depends optional="true" config-file="myPluginId-withKotlin.xml"> org.jetbrains.kotlin </depends>
incompatible-with
Supported since 2020.2
Declares incompatibility with a provided module.
Reference: Declaring Incompatibility with Module
- Required
no; ignored in additional config file
- Example
- <incompatible-with> com.intellij.modules.appcode.ide </incompatible-with>
resource-bundle
A resource bundle to be used with message key attributes in extension declarations and for action and group localization. A single <idea-plugin>
element can contain multiple <resource-bundle>
elements.
- Required
no
- Example
To load the content of messages/Bundle.properties bundle, declare:
<resource-bundle>messages.Bundle</resource-bundle>
applicationListeners
Defines the application-level listeners.
Reference: Defining Application-Level Listeners
- Required
no
- Children
projectListeners
Defines the project-level listeners.
Reference: Defining Project-Level Listeners
- Required
no
- Children
listener
Defines a single application or project-level listener. A single <applicationListeners>
or <projectListeners>
can contain multiple <listener>
elements.
Reference: Listeners
- Required
no
- Attributes
topic
(required)The fully qualified name of the listener interface corresponding to the type of received events.
class
(required)The fully qualified name of the class implementing the listener interface that receives and handles the events.
os
(optional; supported since 2020.1)Restricts listener instantiation to a specific operating system. Allowed values:
freebsd
mac
linux
unix
windows
activeInTestMode
(optional)Boolean flag defining whether the listener should be instantiated in test mode.
Default value:
true
.activeInHeadlessMode
(optional)Boolean flag defining whether the listener should be instantiated in headless mode.
Default value:
true
.
- Example
- <listener topic="com.intellij.ide.AppLifecycleListener" class="com.example.MyListener" os="mac" activeInTestMode="false"/>
actions
Defines the plugin actions.
Reference: 操作
- Required
no
- Attributes
resource-bundle
(optional; supported in 2020.1+)Defines the dedicated actions resource bundle. See Localizing Actions and Groups for more details.
- Children
- Example
- <actions resource-bundle="messages.ActionsBundle"> <!-- Actions/Groups defined here will use keys from the ActionsBundle.properties bundle. --> </actions>
action
A single action entry of the <actions>
implemented by the plugin. A single <actions>
element can contain multiple <action>
elements.
Reference: Registering Actions in plugin.xml
- Required
no
- Attributes
id
(required)A unique action identifier. The action identifier must be unique between different plugins. Thus, it is recommended to prepend it with the value of the plugin
<id>
.class
(required)The fully qualified name of the action implementation class.
text
(required if the action is not localized)The default long-version text to be displayed for the action (tooltip for toolbar button or text for menu item).
description
(optional)The text which is displayed in the status bar when the action is focused.
icon
(optional)The icon that is displayed on the toolbar button or next to the action menu item. See Working with Icons and Images for more information about defining and using icons.
use-shortcut-of
(optional)The ID of the action whose keyboard shortcut this action will use.
- Children
- Examples
Action declaring explicit
text
:<action id="com.example.myframeworksupport.MyAction" class="com.example.impl.MyAction" text="Do Action" description="Do something with the code" icon="AllIcons.Actions.GC"> <!-- action children elements --> </action>Action without the
text
attribute must use the texts from the resource bundle declared with the<resource-bundle>
element, or theresource-bundle
attribute of the<actions>
element:<action id="com.example.myframeworksupport.MyAction" class="com.example.impl.MyAction" icon="AllIcons.Actions.GC"/>
add-to-group
Specifies that the action should be added to an existing group. A single action can be added to multiple groups.
- Required
no
- Attributes
group-id
(required)Specifies the ID of the group to which the action is added. The group must be an implementation of the
DefaultActionGroup
class.anchor
(optional)Specifies the position of the action in the relative to other actions. Allowed values:
first
- the action is placed as the first in the grouplast
(default) - the action is placed as the last in the groupbefore
- the action is placed before the action specified by therelative-to-action
attributeafter
- the action is placed before the action specified by therelative-to-action
attribute
relative-to-action
(required ifanchor
isbefore
/after
)The action before or after which the current action is inserted.
- Example
- <add-to-group group-id="ToolsMenu" anchor="after" relative-to-action="GenerateJavadoc"/>
keyboard-shortcut
Specifies the keyboard shortcut for the action. A single action can have several keyboard shortcuts.
- Required
no
- Attributes
keymap
(required)Specifies the keymap for which the action shortcut is active. IDs of the standard keymaps are defined as constants in the KeymapManager class.
first-keystroke
(required)Specifies the first keystroke of the action shortcut. The keystrokes are specified according to the regular Swing rules.
second-keystroke
(optional)Specifies the second keystroke of the action shortcut.
remove
(optional)Removes a shortcut from the specified action.
replace-all
(optional)Removes all keyboard and mouse shortcuts from the specified action before adding the specified shortcut.
- Examples
Add the first and second keystrokes to all keymaps:
<keyboard-shortcut keymap="$default" first-keystroke="control alt G" second-keystroke="C"/>Remove the given shortcut from the Mac OS X keymap:
<keyboard-shortcut keymap="Mac OS X" first-keystroke="control alt G" second-keystroke="C" remove="true"/>Remove all existing keyboard and mouse shortcuts and register one for the Mac OS X 10.5+ keymap only:
<keyboard-shortcut keymap="Mac OS X 10.5+" first-keystroke="control alt G" second-keystroke="C" replace-all="true"/>
mouse-shortcut
Specifies the mouse shortcut for the action. A single action can have several mouse shortcuts.
- Required
no
- Attributes
keymap
(required)Specifies the keymap for which the action shortcut is active. IDs of the standard keymaps are defined as constants in the KeymapManager class.
keystroke
(required)Specifies the clicks and modifiers for the action. It is defined as a sequence of words separated by spaces:
modifier keys:
shift
,control
,meta
,alt
,altGraph
mouse buttons:
button1
,button2
,button3
button double-click:
doubleClick
remove
(optional)Removes a shortcut from the specified action.
replace-all
(optional)Removes all keyboard and mouse shortcuts from the specified action before adding the specified shortcut.
- Examples
Add the shortcut to all keymaps:
<mouse-shortcut keymap="$default" keystroke="control button3 doubleClick"/>Remove the given shortcut from the Mac OS X keymap:
<mouse-shortcut keymap="Mac OS X" keystroke="control button3 doubleClick" remove="true"/>Remove all existing keyboard and mouse shortcuts and register one for the Mac OS X 10.5+ keymap only:
<mouse-shortcut keymap="Mac OS X 10.5+" keystroke="control button3 doubleClick" replace-all="true"/>
override-text
Defines an alternate version of the text for the menu action or group.
- Supported
2020.1+ for actions
2020.3+ for groups
- Required
no
- Attributes
place
(required)Declares where the alternate text should be used.
text
(text
oruse-text-of-place
is required)Defines the text to be displayed for the action.
use-text-of-place
(text
oruse-text-of-place
is required)Defines a location whose text should be displayed for this action.
- Examples
Explicitly overridden text:
<override-text place="MainMenu" text="Collect _Garbage"/>Overridden text reused from the
MainMenu
place:<override-text place="EditorPopup" use-text-of-place="MainMenu"/>
abbreviation
Defines an alias for the action name which the user can use in or popups. A single action can have multiple abbreviations.
- Required
no
- Attributes
value
(required)The abbreviation value.
- Example
- <abbreviation value="abc"/>
synonym
Defines an alternative name for searching the action by name. A single action can have multiple synonyms.
- Supported
2020.3+
- Required
no
- Attributes
text
(required)The synonym text.
- Example
- <synonym text="GC"/>
group
Defines an action group. The <action>
, <group>
and <separator>
elements defined inside the group are automatically included in it. The <group>
elements can be nested.
Reference: Grouping Actions
- Required
no
- Attributes
id
(required)A unique group identifier. The group identifier must be unique between different plugins. Thus, it is recommended to prepend it with the value of the plugin
<id>
.class
(optional)The fully qualified name of the group implementation class. If not specified,
DefaultActionGroup
is used.text
(required if thepopup
istrue
and group is not localized)The default long-version text to be displayed for the group (text for the menu item showing the submenu).
description
(optional)The text which is displayed in the status bar when the group is focused.
icon
(optional)The icon that is displayed next to the group menu item. See Working with Icons and Images for more information about defining and using icons.
popup
(optional)Boolean flag defining whether the group items are presented in the submenu popup.
true
- group actions are placed in a submenufalse
(default) - actions are displayed as a section of the same menu delimited by separators
compact
(optional)Boolean flag defining whether disabled actions within this group are hidden. If the value is:
true
- disabled actions are hiddenfalse
(default) - disabled actions are visible
use-shortcut-of
(optional)The ID of the action whose keyboard shortcut this group will use.
searchable
(optional; supported in 2020.3+)Boolean flag defining whether the group is displayed in
or
popups.
Default value:
true
.
- Children
- Examples
Group declaring explicit
text
:<group id="com.example.myframeworksupport.MyGroup" popup="true" text="My Tools"> <!-- group children elements --> </group>A popup group without the
text
attribute must use the texts from the resource bundle declared with the<resource-bundle>
element, or theresource-bundle
attribute of the<actions>
element:<group id="com.example.myframeworksupport.MyGroup" popup="true"/>A group with custom implementation and icon:
<group id="com.example.myframeworksupport.MyGroup" class="com.example.impl.MyGroup" icon="AllIcons.Actions.GC"/>
reference
Allows adding an existing action to the group. The element can be used directly under the <actions>
element, or in the <group>
element.
- Required
no
- Attributes
ref
(required)The ID of the action to add to a group.
- Children
- Examples
An action reference in a group:
<group ...> <reference ref="EditorCopy"/> </group>An action reference registered directly in the
<actions>
element:<actions> <reference ref="com.example.MyAction"> <add-to-group group-id="ToolsMenu"/> </reference> </group>
separator
Defines a separator between actions in a group. The element can be used directly under the <actions>
element with the child <add-to-group>
element defining the target group, or in the <group>
element.
- Required
no
- Attributes
text
(optional)Text displayed on the separator. Separator text is displayed only in specific contexts such as popup menus, toolbars, etc.
key
(optional)The message key for the separator text. The message bundle for use should be registered via the
resource-bundle
attribute of the<actions>
element. The attribute is ignored if thetext
attribute is specified.
- Children
- Examples
A separator dividing two actions in a group:
<group ...> <action .../> <separator/> <action .../> </group>A separator registered directly in the
<actions>
element:<actions> <separator> <add-to-group group-id="com.example.MyGroup" anchor="first"/> </separator> </group>A separator with a defined text:
<separator text="Group By"/>A separator with a text defined by message key:
<separator key="message.key"/>
extensions
Defines the plugin extensions.
Reference: Extensions
- Required
no
- Attributes
defaultExtensionNs
(optional)Default extensions namespace. It allows skipping the common prefix in fully qualified extension point names. Usually, the
com.intellij
namespace is used when the plugin implements IntelliJ Platform extensions.
- Children
The children elements are registrations of the extension points defined by
<extensionPoint>
elements. Extension elements names follow the EPs names defined byname
orqualifiedName
attributes.- Example
Extensions declaration with the default namespace:
<extensions defaultExtensionNs="com.intellij"> <applicationService serviceImplementation="com.example.Service"/> </extensions>Extensions declaration using the fully qualified extension name:
<extensions> <com.example.vcs.myExtension implementation="com.example.MyExtension"/> </extensions>
extensionPoints
Extension points defined by the plugin.
Reference: Extension Points
- Required
no
- Children
extensionPoint
A single extension point entry of the <extensionPoints>
defined by the plugin. A single <extensionPoints>
element can contain multiple <extensionPoint>
elements.
Reference: Declaring Extension Points
- Required
no
- Attributes
name
(name
orqualifiedName
is required) The extension point name that should be unique in the scope of the plugin, e.g.,myExtension
. The fully qualified name of the extension point is built at runtime by prepending the value of thename
attribute with the plugin<id>
+.
prefix. Only one of thename
andqualifiedName
attributes can be specified. Example: when thename
ismyExtension
and plugin ID iscom.example.myplugin
, the fully qualified name of the EP will becom.example.myplugin.myExtension
.qualifiedName
(name
orqualifiedName
is required) The fully qualified name of the extension point. It should be unique between different plugins, and it is recommended to include a plugin ID to guarantee uniqueness, e.g.,com.example.myplugin.myExtension
. Only one of thename
andqualifiedName
attributes can be specified.interface
(interface
orbeanClass
is required) The fully qualified name of the interface to be implemented for extending plugin's functionality. Only one of theinterface
andbeanClass
attributes can be specified. See Extension Points for more information.beanClass
(interface
orbeanClass
is required) The fully qualified name of the extension point bean class providing additional information to the plugin. Only one of theinterface
andbeanClass
attributes can be specified. See Extension Points for more information.dynamic
(optional) Boolean value defining whether the extension point meets the requirements to be dynamic, which is a prerequisite for dynamic plugins. Default value:false
.area
(optional) The scope in which the extension is instantiated. Allowed values:IDEA_APPLICATION
(default)IDEA_PROJECT
IDEA_MODULE
(deprecated)
It is not recommended to use non-default values.
- Children
with
Specifies the required parent type for class names provided in extension point tags or attributes. A single <extensionPoint>
element can contain multiple <with>
elements.
- Required
no
- Attributes
tag
(tag
orattribute
is required)The name of the tag holding the fully qualified name of the class which parent type will be limited by the type provided in the
implements
attribute. Only one of thetag
andattribute
attributes can be specified.attribute
(tag
orattribute
is required)The name of the attribute holding the fully qualified name of the class which parent type will be limited by the type provided in the
implements
attribute. Only one of thetag
andattribute
attributes can be specified.implements
(required)The fully qualified name of the parent type limiting the type provided in the place specified by
tag
orattribute
.
- Example
An extension point which restricts the type provided in a
myClass
attribute to be an instance ofcom.example.ParentType
, and the type provided in asomeClass
element to be an instance ofjava.lang.Comparable
:<extensionPoint name="myExtension" beanClass="com.example.MyExtension"> <with attribute="myClass" implements="com.example.ParentType"/> <with tag="someClass" implements="java.lang.Comparable"/> </extensionPoint>When using the above extension point, an implementation could be registered as follows:
<myExtension ... myClass="com.example.MyCustomType"> <someClass>com.example.MyComparable</someClass> </myExtension>where:
com.example.MyCustomType
must be a subtype ofcom.example.ParentType
com.example.MyComparable
must be a subtype ofjava.lang.Comparable
Deprecated Elements
application-components
Defines a list of application components.
- Required
no
- Children
project-components
Defines a list of project components.
- Required
no
- Children
module-components
Defines a list of module components.
- Required
no
- Children
component
Defines a single application, project, or module component. A single <application-components>
, <project-components>
, or <module-components>
element can contain multiple <component>
elements.
- Required
no
- Children
implementation-class
The fully qualified name of the component implementation class.
- Required
yes
interface-class
The fully qualified name of the component interface class. If not specified, the interface will be the same as defined by <implementation-class>
element.
- Required
no
headless-implementation-class
The fully qualified name of the component implementation class to be used when the IDE runs in headless mode.
- Required
no
option
Allows to provide additional component options. A single <component>
element can contain multiple <option>
elements.
- Required
no
- Attributes
name
(required)Option name.
value
(required)Option value.
loadForDefaultProject
If present, the component is instantiated also for the default project. It takes effect only when used inside of <project-components>
element.
- Required
no