JIRA is now available as three separate applications, JIRA Software, JIRA Service Desk, and JIRA Core. For more information on administering these applications, refer to the Administering JIRA Applications documentation.

Upgrading JIRA Manually

If you're upgrading to JIRA 7.0, you should consult the Migration hub. JIRA 7.0 contains functionality that affects your user management, application access and log in permissions, and it's very important that you understand the requirements and the implications before you upgrade. The Migration hub has all this information in one handy space.

This page describes how to upgrade JIRA installations that don't support the rapid upgrade method or fallback method. You should use this method to upgrade JIRA if you meet any of the following criteria:

  • You use a WAR distribution of JIRA version 4.0.0 or later.
  • You use JIRA 4.0.0 or later on Solaris.
  • You use JIRA 4.0.0 – 4.2.x on Windows or Linux.
  • You use JIRA prior to 4. Note that these versions will require an upgrade to JIRA 4.4.5 before moving on with newer versions.

See Upgrading JIRA for more information on the methods you can use to upgrade JIRA.

On this page:

1. Before you start

  1. Read about the new version - Review the release notes and upgrade notes for the version of JIRA that you are upgrading to. See Production Releases. If you plan to skip a few JIRA versions during your upgrade, we strongly recommend that you read the upgrade guides for all major versions between your current version and the version to which you are upgrading. Refer to Important Version-Specific Upgrade Notes for quick links to these guides.
  2. Check your license - Verify that your license support period is still valid. Upgrading to a version prior to JIRA 6.2.4 on an expired license could lead to the error described in After upgrade JIRA shows 500 error page with message User has no unique key mapping.
  3. Check for known issues - Use the JIRA Knowledge Base to search for any issues in the new version that will affect you.
  4. Check for compatibility:
    • Confirm that your operating system, database, other applicable platforms and hardware still comply with the requirements for JIRA 6.4. The End of Support Announcements for JIRA page also has important information regarding platform support for future versions of JIRA.
    • If you have installed JIRA plugins (i.e. not included with JIRA), verify that they will be compatible with the version of JIRA you are upgrading to. You can find a plugin's compatibility information using Checking add-on compatibility with application updates or from the plugin's home page on the Atlassian Plugin Exchange.
    • Some anti-virus or other Internet security tools may interfere with the JIRA upgrade process and prevent the process from completing successfully. If you experience or anticipate experiencing such an issue with your anti-virus/Internet security tool, disable this tool before proceeding with the JIRA upgrade.

We strongly recommend performing your upgrade in a test environment first. Do not upgrade your production JIRA server until you are satisfied that your test environment upgrade has been successful.

  • If you have any problems with your test environment upgrade which you cannot resolve, create an issue at our support site so that we can assist you.
  • If you have any problems during the upgrade of your production JIRA server, do not allow your users to start using this server. Instead:
    • Continue to use your old JIRA server — this will help ensure that you do not lose production data.
    • Also create an issue at our support site so that we can help you resolve the problems with your upgrade.

2. Backing up

Before you begin the JIRA upgrade, we strongly recommend that you back up your existing JIRA installation.

2.1 Stop users from updating JIRA data

During the upgrade process, you'll export JIRA's database from your existing JIRA installation (via an XML backup) and then restore this backup into a new JIRA installation. To ensure that the data in the XML backup is consistent with the latest data in the system, you must temporarily restrict access to JIRA so users can't update the data. Refer to the Preventing users from accessing JIRA during backups page for more information.

(warning) Be aware! Inconsistent XML backups cannot be restored!

2.2 Back up your database

Perform an XML backup of your existing JIRA installation's external database. For large JIRA installations, this process may require several hours to complete.

The 'embedded database' is the HSQLDB database supplied with JIRA for evaluation purposes only. If you accidentally use the HSQLDB database in a production system, perform an XML backup of this database and continue on with this procedure.

2.3 Back up your JIRA Home directory

  1. Shut down JIRA.
  2. Locate the JIRA Home directory. You can find information about the location of the directory by navigating to the <jira-application-dir>/WEB-INF/classes/jira-application.properties file in your JIRA Installation Directory. Alternatively, you can open the JIRA Configuration Tool to see the directory that is set as your JIRA Home.
  3. Navigate to the directory specified in the configuration file and create a backup of it in another directory.
  4. (error) Delete the file <jira-home>/dbconfig.xml as soon as the backup is complete.

2.4 Back up your attachments and index directories if located outside your JIRA Home directory

If the attachments and index directories are located outside of your JIRA Home Directory, you must back them up separately. These pages describe how to find out where these directories are located in your implementation:

  • Your attachments directory — Refer to Configuring File Attachments page in the documentation for your version of JIRA.
  • Your index directory — Refer to Search Indexing page in the documentation for your version of JIRA.

Also refer to Backing Up Data for more information about backing up attachments in JIRA.

2.5 Back up your JIRA Installation directory

The 'JIRA Installation Directory' is the directory into which the JIRA application files and libraries were extracted when JIRA was installed.

3. Setting up your new JIRA installation

If you are running a 'mission-critical' JIRA server, we highly recommend performing the remaining steps of this guide in a test environment (e.g. using a separate test JIRA database and a copy of your JIRA Home directory) before performing the upgrade in production.  

3.1 Install the new version of JIRA

Download and extract the JIRA distribution you require to a new directory. Do not overwrite your existing JIRA installation. Ensure this has been shut down and install the new JIRA version to a new location.

Follow the installation instructions for either:

(info) If you are using JIRA WAR, remember to build your new JIRA web application and deploy it to your server. For specific instructions, refer to the JIRA WAR installation page for your application server within the Installing JIRA WAR section.

3.2 Point your new JIRA to (a copy of) your existing JIRA Home directory

If your new JIRA 6.4 installation is on a new server, copy the backup of your existing JIRA Home Directory from the old server to the new server before proceeding.

To set up a "recommended" (not WAR) distribution:

  1. Open the JIRA Configuration Tool.
  2. Click the JIRA Home tab.
  3. Update the JIRA Home Directory field:
    • If your JIRA 6.4 installation is on a new server, update the JIRA Home Directory field to the path of your copied JIRA Home directory.
    • If your JIRA 6.4 installation is on the same server, update the JIRA Home Directory field to the path of your existing JIRA Home directory.
      (info) For more information about this directory, see JIRA Home Directory.

To set up a WAR distribution:

  1. Edit the jira-application.properties file located within the <jira-application-dir>/WEB-INF/classes subdirectory of your new JIRA 6.4 Installation Directory JIRA Installation Directory.
  2. Update the jira.home property in this file to the path of the new JIRA Home Directory:
    • If your JIRA 6.4 installation is on a new server, update the jira.home property to the path of your copied JIRA Home directory.
    • If your JIRA 6.4 installation is on the same server, update the jira.home property to the path of your existing JIRA Home directory.
      (info) For more information about this directory, see JIRA Home Directory.
  3. Remove the '#' at the beginning of the jira.home line (so that JIRA no longer regards this line as a comment).
  4. Save your updated jira-application.properties file.

(tick) You can also set your JIRA Home Directory's location by defining an operating system environment variable JIRA_HOME. This value of this variable takes precedence over the value of the jira.home property in the jira-application.properties file in your JIRA Installation Directory. See Setting your JIRA Home Directory for details.

3.3 Connect the new version of JIRA to a new, empty database

Create a new, empty database that your new JIRA installation will use to store its data.

Follow the appropriate 'Connecting JIRA to...' instructions for your database from stage 2, although from stage 4 of that procedure, be aware of the yellow note below:

If you are using a database (called jiradb, for example) with your existing JIRA installation and the database for your new JIRA installation is running on the same machine or database server, create your new database with a different name (e.g. something intuitive like jiradb_440 for JIRA 4.4.0). However, ensure the new database has identical access permissions to the old JIRA database. Consult your database administrator if you need assistance with this.

(info) You do not need to create a new database if you are using the embedded HSQL database.

3.4 Migrate your existing JIRA configurations over to your new JIRA installation

If you have modified properties in configuration files of your existing JIRA installation, make the same modifications in your new JIRA installation. However, because the properties in the configuration files may have changed between versions, you cannot simply copy the configuration files from your existing installation and replace the equivalent files in the new installation.

For each file you have modified in your existing JIRA installation, you need to manually edit each equivalent file in your new JIRA installation and re-apply your modifications. If a file is not present in your new JIRA installation (for example, osuser.xml in recent JIRA versions), then simply copy that file over to your new JIRA installation.

The table below lists the most commonly modified files and their locations within your JIRA Installation Directory:


Location in 'recommended' (formerly 'Standalone') JIRA distributions

Location in JIRA WAR





Location of the JIRA Home Directory and Advanced JIRA Configuration in JIRA 4.3.x and earlier.

Any custom property values defined in the jira-application.properties file of your existing JIRA 4.3.x (or earlier) installation must be migrated across to the jira-application.properties file of your new JIRA 6.4 installation before you start your new JIRA installation.

Upon starting your new JIRA installation, any custom property values in the jira-application.properties file will automatically be migrated across to either the JIRA database or jira-config.properties file. jira.home is the only property of the jira-application.properties file subsequently used by JIRA.

setenv.bat (Windows) or setenv.sh (Linux)


Application server's bin directory

Increasing JIRA Memory

(not required if upgrading from JIRA 4.3.0 or later)



Modified if you have integrated LDAP with JIRA, integrated Crowd with JIRA, or if you are using a custom form of external user management or user authentication.




Modified if you have integrated Crowd with JIRA.



Application server's conf directory

Modified in the following situations:

(tick) The version-specific upgrade notes contain details on properties which may have changed in these commonly modified files.

In addition to the files above, you should also consider and/or perform the following configurations as part of the upgrade process:

  • Using JIRA with Atlassian's Crowd? — If you are using Crowd with JIRA, configure your new JIRA to talk to Crowd as described in Integrating Crowd with JIRA.
  • Allocating additional memory to JIRA — If you had previously allocated additional memory to JIRA, do the same for your new JIRA instance. For more information refer to Increasing JIRA memory.
  • Plugins — For any plugins that you had installed in your old JIRA, download the plugin version for your new version of JIRA from the http://plugins.atlassian.com site.
  • Character encoding — Ensure that character encoding (i.e. locale) is the same on the new and old locations. Your new version of JIRA may not function correctly if attachments are moved between two system with incompatible encoding.
  • Customisations — If you had made any customisations (code, templates or configuration files), copy over compatible versions of these changes to the new JIRA. (The developers within your organisation who made the customisations to your old version will need to build and test equivalent changes for the new version, and provide you with the files to copy to your upgraded JIRA installation.)
  • (Optional) Running JIRA on a different port — If your new JIRA is installed on the same machine as your old JIRA, you may wish to make sure it runs on a different port (in case you ever need to restart your old JIRA). See Changing JIRA's TCP Ports for details.

3.5 Start your new version of JIRA

  1. Verify that your old JIRA installation is shut down — if this JIRA server is still operating, shut it down.
  2. If you installed the JIRA WAR distribution within Tomcat, delete the Tomcat work directory before restarting JIRA. If you do not do this, users may encounter errors when they try to display JIRA pages.
  3. Start up your new version of JIRA. For:
    • 'Recommended' distributions — follow the Starting JIRA instructions.
    • WAR distributions — follow the instructions for starting JIRA for your application server within the Installing JIRA WAR section.
      (info) During the startup process, your new JIRA installation will create any required database indexes. If you created any custom database indexes, please check them afterwards and remove any that duplicate the indexes added by JIRA.

Do not restart your old JIRA installation...

If your new JIRA 6.4 installation is on the same server as your old one, it may still be configured to use the same JIRA Home directory as your new JIRA installation. Running two separate JIRA installations which share a common JIRA Home directory can lead to serious data corruption.

Nevertheless, we recommend that you do not delete any aspect (or backed up component) of your old JIRA installation, until you are satisfied that your upgraded JIRA installation is functioning as expected.

3.6 Import your old JIRA data into your new JIRA

After you have started your new JIRA installation, import the data from your old instance into the new instance. You will need the backup file of data from your old JIRA that you created earlier in these instructions (above).

To import your old JIRA data into your new JIRA:

  1. Log in as a user with the 'JIRA System Administrators' global permission.
  2. Select Administration > System > Import & Export > Restore System (tab) to open the 'Restore JIRA data from Backup' page.
    (tick) Keyboard shortcut: 'g' + 'g' + type 'rest'
  3. In the File name field, specify the XML backup file you created previously during the export process (above). That zipped file should contain two xml files: activeobjects.xml and entities.xml. Both of these files must be included in the zipped file for the import process to work.
  4. Restore the attachments directory that you backed up previously, into the attachments directory of your new JIRA. (See Restoring Data.)
    (info) Avoid passing through a proxy when performing an XML restore, especially if your JIRA instance is very large. Using a proxy may cause timeout errors.
  5. Access JIRA via your web browser again and log in using a username from your previous JIRA installation.
  6. Take a quick look around your JIRA site to confirm that your projects and issues are present and everything looks normal. You should see the new JIRA version number in the page footer.

4. Post upgrade checks and tasks

It is strongly recommended that you perform the following checks and tasks after you have started your new instance of JIRA:

  1. Check your server logs for error messages, even if JIRA appears to be running correctly. If there are any errors there that you cannot resolve, create a support case in https://support.atlassian.com, attach your log file and we will advise you on the errors.
  2. If you were previously using External User Management, enable it in the new JIRA instance.
  3. If you changed machines when upgrading, change the paths to the indexes, attachments and backup directories, from within the Administration section of JIRA.
  4. Enable email, if you disabled it during testing.
  5. If you migrated any customisations from your old JIRA to the new JIRA, ensure that they are tested thoroughly.
    1. If you had downloaded plugins for the new version of JIRA, install the downloaded JAR file(s) in your new JIRA version and carry out any other required installation for the plugin.
    2. If the plugin has a properties file, apply the same changes to it as you had in the old properties file (don't just copy over the old properties file).

Congratulations! You have completed your JIRA migration/upgrade.

See Also

Disabling Auto-Export
Restoring Data
Upgrading JIRA
Switching Application Servers to Apache Tomcat
Switching Databases

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

21 Archived comments

  1. User avatar


    OK I'm confused. Section 3.1 says

    Do not overwrite your existing JIRA installation. Simply shut this down and install the new JIRA version to a new location.

    But why is there an option to upgrade in the Windows installer package! I'm assuming that this option should be ignored and a fresh install made, but if it is indeed possible to just use this option and the existing 4.1.2 installation that I have will be magically upgraded without having to manually edit config files, that would make my day!


    03 Aug 2011
    1. User avatar

      Giles Gaskell

      Hi Joe,

      Unfortunately your assumption is indeed correct. You cannot use the upgrade feature of the JIRA 4.4 installer packages to upgrade a JIRA installation prior to version 4.3.0.

      I've created this improvement request to clarify the wording on the installer package.

      Kind regards,

      07 Aug 2011
  2. User avatar

    Lee Anne Pedersen

    Should steps 3.3 and 3.4 be reversed? I used the JIRA configuration tool in the v4.4 installation directory, saved the settings before proceeding to 3.4. It saved the new settings to the dbconfig.xml file in the empty v4.4 home directory, and I edited the file manually to add the SQL instance name.

    Step 3.4 created another dbconfig.xml file in the existing home directory but without my manual changes for the instance name. So I just ended up overwriting it with the version from step 3.3.

    11 Aug 2011
    1. User avatar

      Giles Gaskell

      Thanks very much Lee Anne,

      I've reversed steps 3.3 and 3.4 on this page. Likewise, I've also moved step 3.4 in the Migrating JIRA to Another Server page in between steps 3.1 and 3.2.

      The issue here is that the JIRA Configuration Tool's 'Save' button saves all (three) configurations (no matter which tab you were on) — not just the specific configuration relating to the tab you clicked the 'Save' button on.

      You may wish to vote on this improvement request if you think the JIRA Configuration Tool should only save specific configurations relating to the tab on which the 'Save' button was clicked.


      12 Aug 2011
  3. User avatar

    Chris Keeble

    We have successfully upgraded from v4.4-beta1#644-r153810 to v4.4.1#660-r161644, following the manual upgrade procedure - but we had to manually remove the old service, install the new service and update the start-service.bat and stop-service.bat files in the new installation. This would appear to be due to changes in the way the JIRA service is named.

    I hope this helps anyone else who attempts the same upgrade scenario, which is understandably unsupported.

    25 Sep 2011
    1. User avatar

      Giles Gaskell

      Thanks for the information Chris. However, would you know if this problem would have been encountered if you had upgraded from JIRA 4.3 directly (rather than via a JIRA development build like JIRA 4.4 Beta 1)?

      The reason I ask is that we do not support upgrade paths to and from JIRA development builds, since there may be changes between (consecutive) JIRA development builds that may break the JIRA upgrade process.



      26 Sep 2011
      1. User avatar

        Chris Keeble

        No, I'm sorry Giles, we've only experienced the upgrade from 4.4.1 BETA to 4.4.1 Production - not having used any of the earlier versions.

        As mentioned in my original post, I'm aware this upgrade path is not supported, but hope the pointer might help others who attempt the same upgrade or find themselves facing the same issue through another upgrade path.

        Kind regards


        26 Sep 2011
        1. User avatar

          Giles Gaskell

          Thanks Chris!

          Regards, Giles.

          30 Sep 2011
  4. User avatar

    zein Mutaqien

    do u know this problem, iam already do this. but i have problem when i run JIRA localhost:8080

    HTTP Status 404 -

    type Status report


    description The requested resource () is not available.

    Apache Tomcat/6.0.32

    08 Mar 2012
    1. User avatar

      Chris Keeble

      You might like to check out this issue, particularly from this comment which talks about the 404 issue we were having:

      JRA-17768 - jira home remains locked after unclean shutdown Resolved


      08 Mar 2012
    1. User avatar

      amit kumar

      post upgrading to Jira 5.0.3, i am getting bad gateway error on jira. anyone faced this issue ? 

      23 May 2012
  5. User avatar

    Michael Hirschler

    Today I was able to upgrade JIRA from version 4.2.4 directly to version 5.0, following this guide.

    Before install the new version, I made a full backup (inclusive XML-Backup).

    But I made one different step: I set the JIRA-HOME (described at 3.3 Point your new JIRA to your existing JIRA Home directory).
    After this, I don't connect to an existing database. I started JIRA (version 5.0) and imported the XML to a new database. I had to do this, because Atlassian recommend to use InnoDB as storage-engine on MySQL-Server. Our first JIRA-Instance was running on a MySQL-Server using MyISAM-Engine. Importing XML had done the job I expected. There no issues I can see.

    Best regards, Michael

    14 Mar 2012
  6. User avatar


    Perhaps note that server.xml needs to be edited to include a JNDI database resource in the case that SQL Server Windows Authentication/NTLM/Trusted Connection is used.  Also dbconfig.xml will need to be manually edited to use this JNDI resource. 

    This isn't mentioned anywhere in the Configuring JIRA with SQL Server 2008 page, although there is a comment from another user to this effect in the version 4.4 upgrade notes.

    03 Sep 2012
  7. User avatar

    Brendan Patterson

    OK! I just upgraded JIRA 4.1 to 5.2.  After much trial and error I found that these instructions are pretty much correct EXCEPT if you're using Crowd then you absolutely must also copy (and possibly adjust) your crowd.properties file from your original JIRA 4.x in WEB-INF/classes/crowd.properties to the same location. 

    This is key and somehow completely missing from the above table.

    I'm going to add it to the table right now and hopefully if I'm somehow wrong the Atlassian doc ninja's will remove the entry, but I'm 97.8% sure this is correct. It's hard to be 100% correct when you're juggling so many variables at one time.

    11 Dec 2012
  8. User avatar

    Dowjones Admin

    I'm a new JIRA admin coming from a confluence background..   on confluence we never used to start with a fresh database between upgrades... whats the reason for this?   I'm concerned because of the sync to AD (25000 users and groups).  Is this really how it's done on JIRA?

    05 Apr 2013
    1. User avatar

      Alex Sanchez

      This is an old post, so I guess you already got your answer.

      But here's some information for people who's having the same question:

      It seems that JIRA does not upgrade an existing database automatically when upgrading. I was hoping for this too, so I did a test myself, but on startup the server was complaining about entity mapping:

      [core.entity.jdbc.DatabaseUtil] WARNING: Column "SEARCH_FIELD" of table "audit_log" of entity "AuditLog" is of type "VARCHAR(255)" in the database, but is defined as type "LONGTEXT" in the entity definition.

      Apparently a column data type was changed (between JIRA 6.1.7 and 6.2.0) but the upgrade did not automatically convert/change the existing database to the new expected schema, even though it detected the discrepancy. 

      So I guess the only way to upgrade your existing data is to create a new fresh database and then import the data from your old database. This is not an issue if you follow this guide without asking any questions, but for us that realize that this is not the most optimal (as in easy for admins) way to upgrade your existing data it would be nice if the reason was explained in this guide.

      11 Mar 2014
  9. User avatar


    For the part to connect to the database -  I recommend just renaming your dbconfig.xml file or deleting it.  That way once you start JIRA the setup process will start on the database setup and you can fill in all the details and this will recreate the dbconfig file.  A lot easier than manipulating an xml file.  imho.  



    09 Aug 2013
  10. User avatar

    Tracey Voss

    So is it true that we cannot upgrade an existing JIRA database schema? We HAVE to start with an empty schema and use the XML import? This is fairly hellish procedure if you have a large database. And as an admin I don't want to use gui tools for this sort of work as I usually have a restricted/secure environment which doesn't allow me to use an x client without doing hand stands and backflips. It would be nice if you could make things a little easier for us non-windows administrators. Cheers

    28 May 2014
    1. User avatar


      Starting with a new schema is required per the upgrade notes.  I used to do a XML import but have transitioned into using db tools to export and import the db's.  Mysql makes this relatively easy with myslqdump and import.  Not sure what db you're using but worth a look.  

      28 May 2014
      1. User avatar

        Tracey Voss

        I'm using postgres and would love to use dump and restore tools. But I thought you had to use the XML import because of DDL changes between application versions? A pg_restore would be restoring data still in the old format and would not be compatible with the new version of jira.

        25 Jun 2014
  11. User avatar

    Trevor Horsfall

    Why are we required, in 2.3 Step #4, to delete the file <jira-home>/dbconfig.xml?  Then later we're forced to re-import the database contents from XML backup?


    If I'm upgrading between JIRA version that support the same database(s) (i.e. JIRA 6.0.7 to 6.0.8), why am I forced to create a new database?  Previously JIRA just upgrades the database contents in-place, if required.

    21 Jan 2015
Powered by Confluence and Scroll Viewport