Documentation for JIRA 4.1. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

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:

  • creating new dashboard gadgets (previously known as 'portlets')
  • creating new reports
  • creating new types of custom fields
  • customising workflow
  • modifying the availability of 'issue operations' links ('Create Issue', etc)

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 Framework​ 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.

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 2' Plugins — These plugins are compatible with the 'new' plugin framework used in JIRA version 4.0 and later. 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

Once you have downloaded or created your plugin jar file, follow these steps to install it in your JIRA instance:
  1. Shut down JIRA.
  2. 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/.
  3. Start up JIRA.
  4. Go to 'Administration > Plugins'. Your plugin (e.g. 'EXAMPLE_PLUGIN') will be listed and enabled.
Icon

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:

  1. Shutting down JIRA,
  2. Moving the plugin jar file to <JIRA installation directory>/atlassian-jira/WEB-INF/lib/
  3. Restarting JIRA.

Updating a JIRA Plugin

The process for updating a plugin is similar to installing a new one. Simply download or create your updated plugin jar, then follow these steps to install it in your JIRA instance:

  1. Shut down JIRA.
  2. Remove the old version of the plugin jar and copy your updated 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/.
  3. Start up JIRA.
  4. Go to 'Administration > Plugins'. The updated version of your plugin (e.g. 'EXAMPLE_PLUGIN') will be listed and enabled.

Disabling a JIRA Plugin

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
  3. On the panel on the left, under the title 'System', click the link labelled 'Plugins'.
  4. This will bring up the 'Current Plugins' page. The page lists all the installed plugins, e.g.:



  5. Locate the plugin that you want to disable, and click the 'Disable plugin' link.

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:

  1. Follow the above steps for disabling a plugin, but click 'Enable plugin' instead.

Uninstalling a JIRA Plugin

Follow these steps to uninstall a plugin from your JIRA instance:

  1. Shut down JIRA.
  2. 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/.
  3. Start up JIRA.
  4. Go to 'Administration > Plugins'. Your plugin (e.g. 'EXAMPLE_PLUGIN') will no longer be listed.