Installing Marketplace apps

The Universal Plugin Manager (UPM) makes it easy to install apps (also known as add-ons or plugins) to extend what your Atlassian application can do.

With just a few clicks, you can browse the Atlassian Marketplace and install apps in your application, all without leaving the administration interface of your Atlassian product.

On this page:

Alternatively, you can install apps by file upload. The file upload procedure installs an app as a JAR or an OBR (OSGi Bundle Repository) file. The archive file should contain the plugin code and resource files. File upload enables you to install custom apps or any app not available on the Atlassian Marketplace. You can also use it to install apps for applications operating behind a firewall and disconnected from the Internet.

A note about safety: apps are very powerful, they can change the behavior of almost any part of the Atlassian application. It's very important that you trust an app before you install it. Always be aware of where (and who) an app comes from.

Plugin framework versions

Apps come in three types: Plugins 1, Pugins 2 (for Server and Data Center applications), and Atlassian Connect (for Cloud applications). The most prominent type is Plugins 2. This version number refers to the version of the underlying Atlassian SDK framework used to build the app. This identifier is distinct from the app's individual versioning scheme.

Apps built with the Plugin 2 SDK use the internal OSGi framework built into Atlassian applications. In some cases, Plugins 1 apps may not be installable in the host application. Instead, you must install them manually. If you attempt to install a Plugins 1 app using file upload when not supported, an error message similar to the following appears:

The add-on name-version.jar is a type 1 add-on. Type 1 add-ons cannot be dynamically installed. For more information on installing type 1 add-ons see the UPM documentation.

Learn more about Installing Plugins 1 type add-ons in JIRA and Bamboo

Installing apps directly from Atlassian Marketplace

If you are connected to the Atlassian Marketplace website from your Atlassian application's administration console, you can install apps by clicking the Install button from the Find new add-ons or Find new apps administration page. This single-click installation method is the quickest way to install apps, although it's not the only way. You can also install by file upload, as described in the next section.

For more information on installing apps from the Find new add-ons or Find new apps page, see Finding new Marketplace apps.

Installing by file upload

You can install most apps using the single-click installation method, as described in Finding new Marketplace apps. Alternatively, you can install an app by uploading it to your Atlassian application. You must use this method to install apps that are not available on the Marketplace, such as a custom app you created, or if installing an older version of an app.

Apps are normally distributed as JAR or OBR (OSGi Bundle Repository) files. These are the only types of app distribution files that are accepted by the file upload mechanism.

Note that some apps are distributed as ZIP files or other types of files other than JARs. These are typically apps that run separately from the host application container, such as the JIRA Client. In Atlassian Marketplace, these entries have a Download button that you click to get the app.

If you attempt to install a file that isn't a JAR or OBR file in the Manage add-ons or Manage apps page, the following error appears:

Could not find a handler capable of installing the app at filename. Check that the file is a valid app.


Could not find a handler capable of installing the add-on at filename. Check that the file is a valid add-on.

You should refer to the installation instructions provided with the app in this case.

Before installing by file upload, make sure that the app distribution file that you want to upload is accessible to your computer either at a file system location or at a network location by URL.

To upload an app manually:

  1. From the top navigation bar in your application, choose > Add-ons or Manage apps.
  2. Click the Upload add-on or Upload app link at the top right side of the page. 
    The following dialog appears.

  3. Enter the location of the JAR or OBR file to upload using the file chooser or by specifying a network location by entering a URL.
  4. Click Upload.
    A confirmation message appears when the app is successfully installed.
  5. If prompted, restart your application to have your change take effect.

You can now manage the app from the user-installed apps list on the Manage add-ons or Manage apps page. 

Installing Plugins 1 type add-ons in JIRA and Bamboo

A few considerations apply to installing or uninstalling add-ons created with the SDK version 1 framework. These types of add-ons are identified in their Marketplace listing as 'Plugins 1' add-ons.

  • You cannot install Plugins 1 add-ons into JIRA or Bamboo using the Universal Plugin Manager. You must download the add-on distribution and follow its specific installation instructions. Such add-ons have a Download button rather than an Install button in their listing. In most cases you will need to move or download the file to the <INSTALL_DIR>/atlassian-jira/WEB-INF/lib directory.
  • Similarly, Plugins 1 JIRA and Bamboo add-ons do not have an Uninstall button. You must remove the add-on from the file system manually.
  • In Confluence, you can install and uninstall Plugins 1 add-ons using the Universal Plugin Manager. You should see an Install or an Uninstall button with the add-on entry.

Once you have downloaded or created your add-on JAR file, follow these steps to install it to JIRA:

  1. Shut down JIRA.
  2. Copy your JAR file (e.g., example_plugin.jar) into the directory:
    • If you are installing a Plugins 1 add-on, copy the JAR file into your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
    • If you are installing a Plugins 2 (OSGi) add-on, copy the JAR file into your JIRA home directory under plugins/installed-plugins/.
  3. Start JIRA.
  4. Confirm the installation by going to Administration > Manage Add-ons. Your add-on (e.g., example_plugin) should appear in the list as enabled.

If you attempt to install a Plugins 1 add-on by copying its JAR file into the installation directory meant for Plugins 2 add-on (or vice versa), JIRA provides a warning indicating that the add-on has been installed into the wrong directory.

However, there may be a very small number of Plugins 1 add-ons (such as the JIRA RPC Plugin) which, if accidentally installed into the Plugins 2 directory (<JIRA home directory>/plugins/installed-plugins/), do not generate this warning. Nevertheless, the add-on does not function correctly and the 'Manage Add-ons' page typically indicates that this add-on has zero modules.

To resolve this problem, reinstall the JAR file into the correct directory as follows:

  1. Shut down JIRA.
  2. Move the JAR file to <JIRA installation directory>/atlassian-jira/WEB-INF/lib/
  3. Restart JIRA.
Last modified on Sep 20, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.