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 Developer Documentation for information on building plugins.
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.
On this page:
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 (
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 find and add a plugin from the Atlassian Plugin Exchange:
Screenshot: Finding a new plugin from the Atlassian Plugin Exchange
Installing your own plugin
To upload your own plugin:
Screenshot: Uploading a new plugin
Installing a plugin manually
You will need to install plugins manually if:
- you are installing a 'Version 1' plugin; or
- your JIRA server does not have access to the internet (in which case the Universal Plugin Manager will be unable to access http://plugins.atlassian.com).
Viewing Installed Plugins
Screenshot: Finding installed JIRA plugins, using the Universal Plugin Manager
Some tabs will not be visible if you do not have the JIRA System Administrators global permission
Updating a JIRA Plugin
To upgrade a plugin:
To upgrade all available plugins:
Disabling a JIRA Plugin
To disable a plugin:
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 enable a plugin:
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 enable 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 uninstall a plugin:
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 configure a plugin: