This page last changed on Feb 21, 2011 by alui.
On this page:
About Plugins
A plugin is a .jar file (containing code, resources and a configuration file) that can be installed into an Atlassian product to add new functionality or change the behaviour of existing features.
You can use plugins to customise and extend the functionality of JIRA in a variety of ways, including:
JIRA ships with a number of preinstalled plugins, and many more are available for download from the Atlassian Plugin Exchange.
You can also create your own plugins — please visit the JIRA Development Hub for information on building 'Version 1' plugins, or visit the Plugin Development Platform for information on building 'Version 2' (OSGi) plugins. These plugins can be installed in your JIRA instance as described below.
Installed JIRA plugins can be enabled or disabled using the Universal Plugin (bundled with JIRA) as described below.
Every plugin is made up of one or more plugin modules. A single plugin may do many things, and each module represents a single function of the plugin. Individual modules can be enabled or disabled, although this is not recommended as modules can often depend on each other. To do so safely would require knowledge of the module interdependencies.
About 'Version 1' Plugins and 'Version 2' Plugins
There are two types of Atlassian plugins:
- 'Version 1' Plugins — These plugins are compatible with the 'old' plugin framework that was used in JIRA prior to version 4.0, and also with the 'new' plugin framework used in JIRA version 4.0 and later. 'Version 1' plugins are installed into your JIRA installation directory under atlassian-jira/WEB-INF/lib/. 'Version 1' plugins must be installed manually (see below) and uninstalled manually (see below).
- 'Version 2' Plugins — These plugins are compatible with the 'new' plugin framework used in JIRA version 4.0 and later. 'Version 2' plugins are installed automatically, using the JIRA administration interface (see below). They are installed into your JIRA home directory under plugins/installed-plugins/. 'Version 2' plugins are deployed in an internal OSGi container to isolate the plugin from the core code and other plugins, and to allow sophisticated dependency management. 'Version 2' plugins have to be specifically declared as such, using the plugins-version="2" attribute in the plugin's configuration file (atlassian-plugin.xml).
How do I tell if a Plugin is 'Version 1' or 'Version 2'?
Go to https://plugins.atlassian.com and look at the plugin's details. The 'Plugin System' field will show 'ONE' for Version 1 plugins and 'TWO' for Version 2 plugins.
Installing a JIRA Plugin
Installing a plugin from the Atlassian Plugin Exchange
To access the Universal Plugin Manager in JIRA,
- Click the 'Administration' link on the top bar to open the administration console.
- Click the 'Plugins' link under the 'System' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your JIRA instance.
To find and add a plugin from the Atlassian Plugin Exchange,
- Click the 'Install' tab in the UPM. The Install Plugins page will display showing the featured plugins for your application (see screenshot below).
- Search for your plugin as follows:
- Enter some keywords that describe your desired plugin, e.g. 'Charting', in the 'Search the Plugin Exchange' search box and press 'Enter' on your keyboard.
- Alternatively, just browse to the desired plugin in the list. choose 'Featured', 'Popular', 'Supported' (by Atlassian) or 'All available' from the 'Plugins to show' dropdown to show a different list of plugins.
- When you have located the desired plugin, click the 'Install' button for the plugin to add it to your application. A confirmation message and the plugin details (see 'Viewing Plugin Details' in the Related Topics below) for the plugin will display, if it is installed successfully.
Note: You may need to restart your application for your change to take effect. The Universal Plugin Manager will inform you if this is the case.
Note: Not all plugins can be automatically installed. Some required manual installation. These plugins will have a 'Download' button instead of an install button. In these cases, you should read and follow that plugin's installation instructions.
Screenshot: Finding a new plugin from the Atlassian Plugin Exchange

Installing your own plugin
To access the Universal Plugin Manager in JIRA,
- Click the 'Administration' link on the top bar to open the administration console.
- Click the 'Plugins' link under the 'System' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your JIRA instance.
To upload your own plugin,
- Click the 'Install' tab in the UPM. The find new plugin page will display showing the featured plugins for your application.
- Click the 'Upload Plugin' link. The 'Upload Plugin' window will display.
- Enter the location of your plugin in either the 'From my computer' or 'From this URL' textbox.
- If the plugin you want to install is on your computer, use the 'Browse' dialogue to choose the plugin file.
- If you want to install a plugin from a remote location, enter the URL of the plugin jar file in to the 'From this URL' field.
- Click the 'Upload' button to upload and enable your plugin. A confirmation message for the plugin will display if it is installed successfully.
Note: You may need to restart your application for your change to take effect. The Universal Plugin Manager will inform you if this is the case.
Screenshot: Uploading a new plugin

Installing a 'Version 1' plugin manually
Once you have downloaded or created your plugin jar file, follow these steps to install it in your JIRA instance:
- Shut down JIRA.
- Copy your plugin jar (e.g. 'EXAMPLE_PLUGIN.jar') into the appropriate plugins directory:
- If you are installing a 'Version 1' plugin, copy the jar into your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
- If you are installing a 'Version 2' (OSGi) plugin, copy the jar into your JIRA home directory under plugins/installed-plugins/.
To find out whether a plugin is Version 1 or Version 2, check the Plugin Exchange. Note that plugins have different versions, and older builds of plugins may be Version 1.
- Start up JIRA.
- Go to 'Administration > Plugins'. Your plugin (e.g. 'EXAMPLE_PLUGIN') will be listed and enabled.
 | If you copy the JIRA jar file of a 'Version 1' plugin into the installation directory for 'Version 2' plugins (or vice versa), JIRA provides a warning, indicating that the plugin has been installed into the wrong directory.
However, there may be a very small number of 'Version 1' plugins (such as the JIRA RPC Plugin) which, when accidentally installed into the 'Version 2' plugins directory (<JIRA home directory>/plugins/installed-plugins/), will not generate this warning. Nevertheless, the plugin will not function correctly and the JIRA administration 'Plugins' page typically indicates that this plugin has zero modules.
To rectify this problem, reinstall the plugin jar to the correct directory by:
- Shutting down JIRA,
- Moving the plugin jar file to <JIRA installation directory>/atlassian-jira/WEB-INF/lib/
- Restarting JIRA.
|
Viewing Installed Plugins
To access the Universal Plugin Manager in JIRA,
- Click the 'Administration' link on the top bar to open the administration console.
- Click the 'Plugins' link under the 'System' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your JIRA instance.
Screenshot: Finding installed JIRA plugins, using the Universal Plugin Manager

Updating a JIRA Plugin
To access the Universal Plugin Manager in JIRA,
- Click the 'Administration' link on the top bar to open the administration console.
- Click the 'Plugins' link under the 'System' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your JIRA instance.
To upgrade a plugin,
- Click the 'Upgrade' tab. The plugin upgrades page will display.
- If you have a version of a plugin installed that is not the latest version available, the latest compatible version of the plugin will be listed on this page.
- You can click the plugin name to expand the row and view more information about the plugin.
- You can filter your list by entering keywords in the 'Filter plugins' text box.
- Click the 'Upgrade Now' button next to the relevant plugin to update it to the plugin version displayed.
To upgrade all available plugins,
- Click the 'Upgrade' tab. The plugin upgrades page will display.
- If you have a version of a plugin installed that is not the latest version available, the latest compatible version of the plugin will be listed on this page.
- You can click the plugin name to expand the row and view more information about the plugin.
- You can filter your list by entering keywords in the 'Filter plugins' text box.
- Click the 'Upgrade all' button next to the relevant plugin, to update each to the plugin version displayed for each plugin.
Note: Some plugins cannot be installed via the Universal Plugin Manager – these plugins must be installed manually. These plugins will not be upgraded automatically.
Disabling a JIRA Plugin
To access the Universal Plugin Manager in JIRA,
- Click the 'Administration' link on the top bar to open the administration console.
- Click the 'Plugins' link under the 'System' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your JIRA instance.
To disable a plugin,
- Click the 'Manage Existing' tab. The plugins installed on your application will be displayed. Enabled plugins will be listed with an
icon.
- Locate the plugin that you want to disable and click the title to expand its plugin details section.
- Click the 'Disable' button.
- Once a plugin has been disabled, you may need to restart your application for your change to take effect. If so, the plugin will display with 'Disabled, requires restart'. This will depend on the plugin and the application.
The plugin will display with an 'Enable' link once your change is applied (i.e. immediately or after an application restart).
Also note that JIRA can automatically disable plugins if they cause errors on startup or initialisation. This is usually caused by having an old version of the plugin that is not compatible with your current version of JIRA. If this occurs, it will be indicated on the 'Current Plugins' page (shown above). You will need to stop JIRA, install the newer version of the plugin and restart JIRA.
Enabling a JIRA Plugin
Note: newly installed plugins are enabled by default.
To access the Universal Plugin Manager in JIRA,
- Click the 'Administration' link on the top bar to open the administration console.
- Click the 'Plugins' link under the 'System' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your JIRA instance.
To enable a plugin,
- Click the 'Manage Existing' tab. The plugins installed on your application will be displayed. Disabled plugins will be listed with an
icon.
- Locate the plugin that you want to enable and click the title to expand its plugin details section.
- Click the 'Enable' button.
- Once a plugin has been enabled, you may need to restart your application for your change to take effect. If so, the plugin will display with 'Enable, requires restart'. This will depend on the plugin and the application.
The plugin will display with an 'Disable' link once your change is applied (i.e. immediately or after an application restart).
Disabling/Enabling all User Installed Plugins (Safe Mode)
Running JIRA in Safe Mode disables all user installed plugins at once. All plugins that were disabled when you entered Safe Mode will be re-enabled when you exit Safe Mode.
To access the Universal Plugin Manager in JIRA,
- Click the 'Administration' link on the top bar to open the administration console.
- Click the 'Plugins' link under the 'System' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your JIRA instance.
To enable Safe Mode,
- Click the 'Manage Existing' tab. The plugins installed on your application will be displayed.
- Click the 'Enable Safe Mode' button.
- Click the 'Continue' button in the confirmation window that displays. All user installed plugins will be disabled and your application will now be running in 'Safe Mode' (see screenshot below).
- You can now make changes to your installed plugins, as desired (e.g. enable/disable specific plugins or plugin modules).
- Exit safe mode by clicking one of the links in the Safe Mode banner:
- Click 'Exit Safe Mode and restore the previous configuration' to exit support mode and restore your plugin configuration prior to entering Safe Mode.
- Click 'Exit Safe Mode and keep the current configuration' to exit support mode and keep any changes made to your plugin configuration during Safe Mode.
Uninstalling a JIRA Plugin
Note: If you only want to temporarily remove a plugin, you may wish to disable it instead of uninstalling it.
To access the Universal Plugin Manager in JIRA,
- Click the 'Administration' link on the top bar to open the administration console.
- Click the 'Plugins' link under the 'System' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your JIRA instance.
To uninstall a plugin via the UPM,
- Click the 'Manage Existing' tab. The plugins installed on your application will be displayed.
- Click the name of the plugin that you wish to uninstall. The plugin details for the plugin will display.
- Click the 'Uninstall' button. The information summary will display an 'Uninstalling' message and the plugin will be uninstalled from your application.
Uninstalling a 'Version 1' plugin manually
- Shut down JIRA.
- Remove your plugin jar (e.g. 'EXAMPLE_PLUGIN.jar') from the appropriate plugins directory:
- If you are removing a 'Version 1' plugin, remove the jar from your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
- If you are removing a 'Version 2' (OSGi) plugin, remove the jar from your JIRA home directory under plugins/installed-plugins/.
- Start up JIRA.
- Go to 'Administration > Plugins'. Your plugin (e.g. 'EXAMPLE_PLUGIN') will no longer be listed.
Configuring a JIRA Plugin
A number of plugins have advanced configuration options, e.g. a plugin may contain multiple 'modules' that you can enable/disable. If you have one of these plugins installed on your application instance, you can view and update these configuration options via the Universal Plugin Manager (UPM).
To access the Universal Plugin Manager in JIRA,
- Click the 'Administration' link on the top bar to open the administration console.
- Click the 'Plugins' link under the 'System' section in the left menu to open the 'Universal Plugin Manager'. The 'Universal Plugin Manager' will be displayed, showing the plugins installed on your JIRA instance.
To configure a plugin,
- Click the 'Manage Existing' tab.
- Locate the plugin that you want to configure in the list of installed plugins and click its title. The plugin details section will expand (see first screenshot below).
- Click the 'Configure' link for that plugin. The link will be disabled if the plugin is disabled. If there is no 'Configure' link, then there are no advanced configuration options available for that plugin.
- The advanced configuration options for the plugin will display (see second screenshot below). Update the configuration settings as desired and save your changes.
Note: The advanced configuration screens are provided by each plugin. If you encounter any problems after you click the 'Configure' link, the plugin is responsible for the issue, not the Universal Plugin Manager.
See Also
|