This document describes the standard, recommended procedure for upgrading to on Linux or Windows.

Use this procedure if:

  • You are upgrading from JIRA Standalone version 4.3.0 or later on Linux or Windows.
        AND
  • You are not changing any of the following:
    • The operating system that will run JIRA.
    • The database that will store JIRA's data.
    • The location of JIRA's index and/or attachments paths.

Otherwise:

  • If any of the first three points applies to your situation AND the fourth point is true, use the manual procedure (see Upgrading JIRA Manually) to upgrade JIRA instead:
    • You are upgrading from JIRA Standalone versions 4.0.0 – 4.2.x.
    • You are upgrading from JIRA WAR version 4.0.0 or later.
    • You are upgrading JIRA Standalone version 4.3.x on Solaris.
          AND
    • You are not changing any of the following:
      • The operating system that will run JIRA.
      • The database that will store JIRA's data.
      • The location of JIRA's index and/or attachments paths.
  • If any of these points applies to your situation, use the migration procedure (see Migrating JIRA to Another Server) to upgrade JIRA instead:
    • You are upgrading from a version of JIRA prior to 4.0.0.
    • You are changing the location of your index and/or attachments path for .
    • You are changing the operating system that will run .
    • You are changing the database or database system that will store JIRA's data.

On this page:

(warning) Please read/perform all steps and sub-steps in consecutive order.

1. Before You Start

2. Upgrade Overview

The upgrade feature of the Linux and Windows Installers, automates the following tasks for you:

  1. Backs up the Installation and Home Directories of the existing JIRA installation to be upgraded.
  2. Installs whilst migrating the following from your existing JIRA installation to the new installation:

The upgrade feature detects and notifies you of any files (other than jira-application.properties and setenv.sh / setenv.bat) in the atlassian-jira subdirectory of your existing JIRA Installation Directory, which had been deleted, added or modified from a 'default' JIRA installation. This informs you of any customisations you will need to migrate manually over to your upgraded JIRA installation directory.

The upgrade feature also re-uses your existing JIRA Home Directory so that any key data stored in this directory from your previous JIRA installation will be retained after the JIRA upgrade.

(info) Please Note:

3. Performing the Upgrade

Refer to the appropriate upgrade instructions below for your operating system:

Upgrading JIRA on Windows

  1. Download the JIRA Standalone 'Windows Installer' (.exe) file (for the new version of JIRA) from the JIRA Download Center.
  2. Run the '.exe' file to start the upgrade wizard.
    (info) If a Windows 7 (or Vista) 'User Account Control' dialog box requests if you want to allow the upgrade wizard to make changes to your computer, specify 'Yes'. If you do not, the installation wizard will have restricted access to your operating system and any subsequent installation options will be limited.
  3. At the 'Upgrading JIRA?' step, choose the 'Upgrade an existing JIRA installation' option.
  4. In the 'Existing JIRA installation directory' field, specify the JIRA Installation Directory of your JIRA installation to be upgraded.
    (info) The upgrade wizard will attempt to find an existing JIRA installation and use its location to pre-populate this field. However, always verify this location, particularly if you have multiple JIRA installations running on the same machine.
  5. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
    1. At the 'Back up JIRA directories' step, ensure the 'Back up these directories' option is selected. This creates 'zip' archive file backups of your existing JIRA Installation and JIRA Home Directories in their respective parent directory locations.
      (info) Please Note:
      • Choosing this option is strongly recommended!
      • At this point, the upgrade wizard notes any customisations in your existing JIRA Installation Directory which it cannot automatically migrate to your upgraded JIRA installation. If you are informed of any files containing such customisations, please make a note of these files as you will need to manually migrate their customisations (which are not mentioned in the overview above) to your upgraded JIRA installation. One relatively common customisation that the upgrade wizard cannot automatically migrate is an SSL configuration defined in the conf/server.xml file of the JIRA Installation Directory.
    2. At the 'Upgrade Check List' step, back up your external database and check that any non-bundled plugins will be compatible with your upgraded JIRA version. You may have already conducted the latter (in step 5 of the Before You Start section above).
    3. Upon clicking 'Next', your existing JIRA installation will be shut down if it is still running. The upgrade wizard will then:
      1. Back up your existing JIRA installation.
      2. Delete the contents of the existing JIRA Installation Directory.
      3. Install the new version of JIRA to the existing JIRA Installation Directory.
      4. Starts your new (upgraded) JIRA installation.
        (warning) If you noted any files that contain customisations which must be migrated manually to your upgraded JIRA installation (above), then:
        1. Stop the upgraded JIRA installation.
        2. Migrate the customisations from these files into the upgraded JIRA Installation Directory.
        3. Restart the upgraded JIRA installation.
  6. At the last step of the upgrade wizard, select the option to launch the upgraded JIRA installation in a browser so you can check the upgrade.

Congratulations, you have completed upgrading your JIRA installation on Windows!

Upgrading JIRA on Linux

  1. Download the appropriate JIRA Standalone 'Linux 64-bit / 32-bit Installer' (.bin) file that suits your operating system (for the new version of JIRA) from the JIRA Download Center.
  2. Open a Linux console and change directory (cd) to the '.bin' file's directory.
    (warning) If the '.bin' file is not executable after downloading it, make it executable, for example:
    chmod a+x atlassian-jira-X.Y.bin
    (where X.Y represents your version of JIRA)
  3. Execute the '.bin' file to start the upgrade wizard.
  4. When prompted to choose between creating a new JIRA installation or upgrading an existing installation, choose the 'Upgrade an existing JIRA installation' option.
  5. Specify the JIRA Installation Directory of your JIRA installation to be upgraded.
    (info) The upgrade wizard will attempt to find an existing JIRA installation and will provide its location as a choice. However, always verify this location, particularly if you have multiple JIRA installations running on the same machine.
  6. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
    1. Choose the option to back up JIRA's directories. This creates 'zip' archive file backups of your existing JIRA Installation and JIRA Home Directories in their respective parent directory locations.
      (info) Please Note:
      • Choosing this option is strongly recommended!
      • At this point, the upgrade wizard notes any customisations in your existing JIRA Installation Directory which it cannot automatically migrate to your upgraded JIRA installation. If you are informed of any files containing such customisations, please make a note of these files as you will need to manually migrate their customisations (which are not mentioned in the overview above) to your upgraded JIRA installation. One relatively common customisation that the upgrade wizard cannot automatically migrate is an SSL configuration defined in the conf/server.xml file of the JIRA Installation Directory.
    2. At the 'Upgrade Check List' step, back up your external database and check that any non-bundled plugins will be compatible with your upgraded JIRA version. You may have already conducted the latter (in step 5 of the Before You Start section above).
    3. Upon proceeding, your existing JIRA installation will be shut down if it is still running. The upgrade wizard will then:
      1. Back up your existing JIRA installation.
      2. Delete the contents of the existing JIRA installation directory.
      3. Install the new version of JIRA to the existing JIRA installation directory.
      4. Starts your new (upgraded) JIRA installation.
        (warning) If you noted any files that contain customisations which must be migrated manually to your upgraded JIRA installation (above), then:
        1. Stop the upgraded JIRA installation.
        2. Migrate the customisations from these files into the upgraded JIRA Installation Directory.
        3. Restart the upgraded JIRA installation.
  7. The last step of the upgrade wizard provides you with a link to launch the upgraded JIRA installation in a browser, so you can check the upgrade.

Congratulations, you have completed upgrading your JIRA installation on Linux!

Upgrade Check List

The upgrade wizard requests that you perform the following tasks before it actually commences the upgrade of your existing JIRA installation.

Back Up Your External Database

Perform a backup of your external database (using your database's native backup tools) and verify that the backup was created correctly.

(warning) Inconsistent database backups may not restore correctly! If you are unfamiliar with your database's native backup/restore facilities, then before proceeding, test your database backup's integrity by:

Alternatively, use the Migrating JIRA to Another Server procedure to upgrade JIRA instead.

Check Plugin Compatibility

As you may have already done in point 5 of the Before You Start section above, if you have installed any additional JIRA plugins (i.e. not included with JIRA), please verify that they will be compatible with the version of JIRA you are upgrading to. You can find a plugin's compatibility information from the the plugin's home page on the Atlassian Plugin Exchange. Once you have confirmed the availability of compatible versions, you should upgrade your plugins after successfully upgrading JIRA. This can be done via the 'Plugin Repository' in JIRA's Administration Area.