Upgrading JIRA applications manually
In this guide, we'll run you through upgrading JIRA manually, if your installation doesn't support using the installer. Upgrading to any later version is free if you have current software maintenance. See our Licensing FAQ to find out more.
You should use this method to upgrade JIRA if you meet any of the following criteria:
Before you begin
Before you upgrade JIRA, there's a few questions you need to answer.
| Is manual the right upgrade method for you? | |
Are you eligible to upgrade? |
Tell me more...
To check if software maintenance is current for your license, go to If your support period has expired, follow the prompts to renew your license and reapply it before upgrading. |
| Have our supported platforms changed? | |
| Do you need to make changes to your environment? | |
| Check some known issues |
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
- Check the Upgrade Notes for the version you plan to upgrade to (and any in between).
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.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.
3. Upgrade JIRA in a test environment
- Create a staging copy of your current production environment.
See Establishing staging server environments for help creating an environment to test your upgrade in. - Follow the steps below to upgrade your test environment.
- Test any unsupported add-ons and customizations before upgrading your production environment.
Upgrade JIRA
4. Back up
Create an XML backup of your database.
Back up your installation directory and home directory.
As soon as the backup is complete, delete the
<home-directory>/dbconfig.xmlfile from your existing home directory. This will allow you to connect JIRA to a new database.
5. Download JIRA
Download the zip or tar.gz archive – JIRA Core or JIRA Software.
6. Extract the file and upgrade JIRA
- Stop JIRA applications.
- Extract (unzip) the files to a directory (this is your new installation directory, and must be different to your existing installation directory).
- Edit the
<installation-directory>\atlassian-jira\WEB-INF\classes\jira-application.propertiesfile to point to your existing JIRA home directory. Make sure that you deleted thedbconfig.xmlfile, otherwise JIRA will try to connect to your existing database. - Copy your jdbc driver jar file from your existing JIRA installation directory to
/libin your new installation directory.
- There are some additional steps you may need to take if:
you use Crowd for user management
you are upgrading from version 4.3.0 or earlier
Click here to expand...The
jira-application.propertiesfile, which you might know from advanced configuration, now contains only the location of your JIRA home directory.You should reapply your advanced configuration settings directly in JIRA by going to
> System > Advanced Settings.
7. Start JIRA and connect it to the database
- Start JIRA to launch the setup wizard. Go to
<installation-directory>/bin, and run thestart-jira.sh/start-jira.batfile. - Access JIRA through your browser, and choose I'll set it up myself to get access to more setup options.
- Select My own database, and provide details of a new, empty database.
Click Import your data, and select the file with your XML backup.
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.- When JIRA starts for the first time after an upgrade, you'll be presented with an overview of the upgrade. This page will show to the first 10 admins who log in to JIRA post upgrade, and only for 14 days. This overview contains information on critical updates to your JIRA instance, and it also gives you a dynamic overview of your add-ons and application links. You can access this information at any time by selecting
> Latest upgrade report. - 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.
After the upgrade
8. Re-apply any modifications
If you have customized JIRA (such as an SSL configuration in the server.xml file, or additional memory allocation in the setenv.sh / setenv.bat file ), you'll need to reapply the customizations to the relevant files in the newly upgraded JIRA installation directory.
9. (Optional) Update JIRA Service Desk
If you're using JIRA Service Desk, you can update it directly in the UI, without downloading a separate installer.
- Go to
> Applications > Versions and licenses. - Update JIRA Service Desk. This will automatically update Service Desk to a compatible version.
Troubleshooting
Did something go wrong?
Check the resources on our Support page, or raise an issue so we can help you resolve your problem.
If you need to retry the upgrade, you must roll back to your previous setup first. Do not attempt to run an upgrade again, or start the older version of JIRA again after an upgrade has failed.