Preparing for the upgrade

All upgrade methods share common pre-upgrade steps that help you prepare for the upgrade. At this point, you shouldn't have to make any changes to your production Jira.

Review upgrade notes

With every Jira release, we publish upgrade notes that might include known issues, important notes related to the upgrade, or additional steps that you need to complete. We’ve summed up all upgrade notes in our upgrade matrix, so you can quickly check whether you need to make some additional changes for your upgrade.

Run health check

Jira has several health checks that let you verify whether your Jira instance is ready for an upgrade. 

  1. In the upper-right corner of the screen, select Administration  > System.
  2. Under System support (the left-side panel), select Troubleshooting and support tools.
  3. Check the results of all instance health checks. Every health check will have a brief description of what it does, and a link to an article with more information, so you know how to fix any detected problems.

  4. Make sure that checks related to the license and database don't report any problems, but you can also fix other detected problems.

    Instance healthchecks.

Check compatibility of apps (add-ons)

Make sure your apps are compatible with the new version, so they keep working after the upgrade. You'll need to disable all incompatible apps as they might affect the upgrade:

  1. In the upper-right corner of the screen, select Administration  > Manage apps.
  2. Scroll down past the list of apps from Atlassian Marketplace, and select JIRA update check.
  3. Select a version you want to upgrade to, and select Check.

    List of compatible apps.
  4. Depending on the compatibility results for your apps, apply the actions described below.

Your apps are incompatible with the new version.

Action: Disable all incompatible apps before you proceed with the upgrade.


Your apps are compatible with the new version.

Action: No action needed, you're good to go.

Compatible, if updated

Your apps will be compatible with the new version once you upgrade them.

Action: Upgrade your apps before you proceed with the upgrade. When you run the Jira update check again, they will be marked as compatible.

Compatible once both are updated

Your apps will be compatible with the new version once you upgrade both Jira and these apps.

Action: We recommend that you disable these apps and proceed with the Jira upgrade. Once you're on a new version, you can upgrade the apps and enable them back.

  1. Disable these apps, because they're incompatible at this point.
  2. Upgrade Jira to a new version.
  3. Upgrade the apps.
  4. Enable the apps.

We can't check the compatibility of this app. It usually applies to custom apps.

Action: It's safer to disable this app, and check how it behaves in a testing environment.

Get your list of files with custom modifications

Have you modified files to customize your Jira? If you want to keep these changes, make sure you know which files have been modified. 

  • If you're on the latest version of the ASTS plugin, go to Administration () > Applications Plan your upgrade to see the list of files in which you introduced custom changes. If you want to keep these changes in your upgraded instance, you need to copy the changes (not entire files!) to the respective files during upgrade. Have this list handy, it will save you time during the upgrade process. 
  • If you cannot pull up the Plan your upgrade page, compile the list of files you've modified. 

For more, see Pre-upgrade planning tool.

If you missed any of the changed files, worry not. We'll show you the files that contain changes that have not been copied over when you start your Jira after upgrade.

Back up your Jira instance

Back up the Jira database and important directories, so you can safely roll back to your previous setup if something goes wrong.


Use the database native tools to create the backup.  If your database doesn't support online backups, you'll need to stop Jira first.

Jira directories

Back up the Jira directories by copying them to some other location.

tip/resting Created with Sketch.

To check the location of all these directories:

  1. In the upper-right corner of the screen, select Administration  > System.
  2. Under System support (the left-side panel), select System info and scroll down to the File Paths section.

  • Back up the Jira installation directory.

  • Back up the Jira home directory.

  • CLUSTER Back up the Jira installation and home directories on all nodes.

  • CLUSTER Back up the shared directory.

All good?

Head back to the landing page, and choose the upgrade method.

Go to landing page

Last modified on Oct 7, 2022

Was this helpful?

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