Upgrading JIRA applications using the installer

In this guide, we'll run you through using the installer to upgrade your JIRA instance to the latest JIRA version on Windows or Linux.

Upgrading to any later version is free if you have current software maintenance. See our Licensing FAQ to find out more.

Before you begin

Before you upgrade JIRA, there's a few questions you need to answer. 

Plan your upgrade

1. Determine your upgrade path

Use the tables below to determine the most efficient upgrade path from your current version to the latest versions of JIRA. 

2. Complete the pre-upgrade checks

1. Check the Upgrade Notes for the version you plan to upgrade to (and any in between).

2. Go to  > System > Support Tools, and check the results of the health check. Fix any detected problems.

   License expired?

   If the software maintenance period included in your license has expired, you can keep using JIRA, but you'll need to renew before you can upgrade.

   Go to > Applications > Versions and licenses, and follow the prompts to renew your license.

   Still using the embedded database?

   If you are using the embedded (trial) database, you should migrate to a different database before upgrading.

   This database is supplied for evaluation purposes only and is not recommended for production environments.

3. Go to  > Add-ons, and scroll down to JIRA update check to check the compatibility of your add-ons. Choose the version you plan to upgrade to, then hit Check.

   If you have incompatible add-ons...

   If your users rely on particular add-ons, you may want to wait until they are compatible before upgrading JIRA. Add-on vendors generally update their add-ons very soon after a major release.

   Good to know:

   • Compatibility information is often not available immediately after a new release. In many cases, the add-on will still work, so give it a try in a test environment before upgrading the production one

3. Upgrade JIRA in a test environment

1. Create a staging copy of your current production environment.
   See Establishing staging server environments for help creating an environment to test your upgrade in.
   
   
2. Follow the steps below to upgrade your test environment.
   
   
3. Test any unsupported add-ons and customizations before upgrading your production environment.

Upgrade JIRA

4. Back up

1. Back up your database and confirm the backup was created properly. 
   You can use the database native tools to create the backup. If your database does not support online backups, you'll need to stop JIRA first.
   
   

2. Back up your installation directory and home directory.
   The installation wizard will back up your JIRA directories as part of the installation process, but you should also back these directories up manually before starting the upgrade.

   Where is my home directory?

   You can find the location of your home directory in the <installation-directory>/atlassian-jira/WEB-INF/classes/jira-application.properties file.

   
   

   The default paths are:

   Windows: C:\Program Files\Atlassian\Application Data\JIRA

   Linux: /var/atlassian/application-data/jira

5. Download JIRA

Download the installer for your operating system – JIRA Core, JIRA Software, or JIRA Service Desk. 

6. Run the installer

1. Run the installer.

   Show me how to do this in Windows...

   Run the .exe file. We recommend using a Windows administrator account.

   If prompted to allow the upgrade wizard to make changes to your computer, choose 'Yes'. If you do not, the installation wizard will have restricted access to your operating system and any subsequent installation options will be limited.

   
   

   Show me how to do this in Linux...

   Change to the directory where you downloaded JIRA, then execute this command to make the installer executable:

   $ chmod a+x atlassian-jira-X.X.X-x64.bin

   Where X.X.X is the JIRA version you downloaded.

   
   

   Next, run the installer – we recommend using sudo to run the installer:

   $ sudo ./atlassian-jira-X.X.X-x64.bin

   You can also choose to run the installer with root user privileges.

2. Follow the prompts to upgrade JIRA:
   
   
   1. When prompted, choose Upgrade an existing JIRA installation.
      
      
   2. Make sure the Existing JIRA installation directory suggested by the wizard is correct (especially important if you have multiple JIRA installations on the same machine.)
      
      
   3. Back up these directories is strongly recommended. This will create a .zip backup of the JIRA home and installation directories.
      
      
   4. The wizard notifies you of customizations in the JIRA installation directory. Make a note of these as you'll need to reapply them later. Your current customizations will be overwritten.
      
      

3. There are some additional steps you may need to take if:

   • you use Crowd for user management

     Click here to expand...

     If you are using Crowd for user management, reapply the modifications from the following files from your existing installation directory to the new files. Do not copy the files as they may be different in the new version of JIRA.

     • <Installation-Directory>/atlassian-jira/WEB-INF/classes/crowd.properties
     • <Installation-Directory>/atlassian-jira/WEB-INF/classes/seraph-config.xml

     
     

After the upgrade

7. Upgrade the database driver

If you're using an Oracle or MySQL database, download the latest jdbc driver and place it in <JIRA-installation-directory>/lib. 

Microsoft SQL and Postgres users can skip this step. 

8. Re-apply any modifications

During the upgrade, the wizard migrated the following from your existing JIRA installation:

• TCP values in the server.xml file.
• Location of your JIRA home directory in the jira-application.properties file.
• The following values in the setenv.sh / setenv.bat file:
  
  • JVM_SUPPORT_RECOMMENDED_ARGS
  • JVM_MINIMUM_MEMORY
  • JVM_MAXIMUM_MEMORY
  • JIRA_MAX_PERM_SIZE

All other customizations need to be reapplied manually.

9. Upgrade your plugins

Once you have confirmed the availability of compatible versions, you should upgrade your plugins after successfully upgrading JIRA. This can be done via  > Add-ons > Manage add-ons.

Troubleshooting