Upgrade with a ZIP Distribution

This page describes how to upgrade an existing YouTrack installation using the YouTrack ZIP distribution. You can use the ZIP distribution to upgrade any existing YouTrack installation.

Prerequisites

Before you upgrade, perform the following prerequisite tasks:

Create a backup of your current database. YouTrack Server does not provide forward database compatibility. Your database is migrated to the format that is compatible with the latest version during the upgrade procedure. This means that you cannot revert to a previous version and continue to use the database that was processed during the upgrade.
Copy the backup of your current database to a secure location just in case you encounter problems with the upgrade and need to roll back to the previous version.
Verify that your YouTrack license supports the upgrade. To view the license limitations, open the Administration menu and select System Settings > Global Settings, then select the License Details tab. If your free update period has expired, you need to extend your subscription.
Mind the recommended upgrade path.

Recommended Upgrade Path

Installation Version	Target Version
Any YouTrack installation earlier than 6.5	YouTrack 6.5
6.5	YouTrack 7.0
7.0	2017.1
2017.x	2018.x
2018.x	2019.x
2019.x	2020.x
2020.x	2021.x
2021.x	2022.x
2022.x	2023.1* --> 2023.2 or 2023.3
2023.2 or 2023.3	2024.1

To locate the current version and build number for your YouTrack Server installation, open the Help menu in the application header

The current version number for a YouTrack Server installation.

Upgrade Existing ZIP Installations

This procedure describes how you can upgrade your current YouTrack ZIP installation to the latest version.

To upgrade an existing YouTrack installation:

Download the ZIP distribution.
Stop the YouTrack service.
Use your operating system tools to verify that all Java processes that are launched by YouTrack are no longer running. If there are YouTrack-related Java processes that are still running, interrupt the outstanding process trees.
If you're upgrading an existing ZIP installation, clear out your <youtrack_home> directory. This directory is the location where the ZIP distribution was unpacked during installation.
Do not extract the ZIP installation file to a directory that contains old files.
We recommend that you perform the following steps:
- Rename the existing <youtrack_home> directory to YouTrack_old (you can use another name).
- Create a new <youtrack_home> directory in the same location as the previous installation.
To upgrade other installations using a ZIP distribution, skip this step and continue.
Extract the contents of the ZIP archive to the empty <youtrack_home> directory.
In a command-line interface, enter a command to start the upgrade:
The commands used to launch the application vary slightly by operating system. To make sure you see information that is relevant to your installation, select the tab that corresponds with the operating system used in your host environment.
- If you enter <youtrack_home>/bin/youtrack.sh run, the console is blocked until the service is stopped.
- If you enter <youtrack_home>/bin/youtrack.sh start, the console is only blocked during the startup process.
If you do not have a web browser installed on the host machine, follow the command with the --no-browser option. For example, <youtrack_home>/bin/youtrack.sh start --no-browser.
To view all the available command options, enter <youtrack_home>/bin/youtrack.sh help.
- If you enter <youtrack_home>\bin\youtrack.bat run, the console is blocked until the service is stopped.
- If you enter <youtrack_home>\bin\youtrack.bat start, the console is only blocked during the startup process.
If you do not have a web browser installed on the host machine, follow the command with the --no-browser option. For example, <youtrack_home>\bin\youtrack.bat start --no-browser.
To view all the available command options, enter <youtrack_home>\bin\youtrack.bat help.
Continue with the upgrade in the web-based Configuration Wizard.
- If you have a browser installed on the host machine, the Configuration Wizard opens automatically.
- If you do not have a web browser installed on the host machine, open the URL of the wizard in a web browser on another workstation. The wizard URL is printed in the console output:
  JetBrains YouTrack <version> will be available on [<YouTrack Base URL>/bundle/starting?wizard_token=<value>] after start
In the Configuration Wizard, click Upgrade.
On the Select Upgrade Source page, click the Select button and select an upgrade source.
You can select the location of a backup or the location of an existing YouTrack Server installation.
When done, click Next.
On the Confirm Settings page, confirm or change your system settings and the location of system directories.
Here you can also enable built-in TLS to secure the network connection for the server. If you want to apply this change during an upgrade installation, follow the instructions for switching to HTTPS during upgrade, starting from the step that tells you to switch to HTTPS.
Review you license. If required, you can also update your license on this page.
When done, click Upgrade.
- YouTrack launches its components.
  Do not close the page in the browser until the setup is complete.
- When the YouTrack Server server is ready, the Dashboard opens. Your YouTrack Server instance is upgraded and ready for use.

Upgrade Non-ZIP Installations

This section describes how you can upgrade your existing non-ZIP YouTrack installation using the ZIP distribution.

To upgrade an existing YouTrack installation:

Download the ZIP distribution.
Create and download a fresh backup of your current database.
Stop the YouTrack service.
Use your operating system tools to verify that all Java processes that are launched by YouTrack are no longer running. If there are YouTrack-related Java processes that are still running, interrupt the outstanding process trees.
Extract the contents of the ZIP archive to the empty <youtrack_home> directory.
In a command-line interface, enter a command to start the upgrade:
The commands used to launch the application vary slightly by operating system. To make sure you see information that is relevant to your installation, select the tab that corresponds with the operating system used in your host environment.
- If you enter <youtrack_home>/bin/youtrack.sh run, the console is blocked until the service is stopped.
- If you enter <youtrack_home>/bin/youtrack.sh start, the console is only blocked during the startup process.
If you do not have a web browser installed on the host machine, follow the command with the --no-browser option. For example, <youtrack_home>/bin/youtrack.sh start --no-browser.
To view all the available command options, enter <youtrack_home>/bin/youtrack.sh help.
- If you enter <youtrack_home>\bin\youtrack.bat run, the console is blocked until the service is stopped.
- If you enter <youtrack_home>\bin\youtrack.bat start, the console is only blocked during the startup process.
If you do not have a web browser installed on the host machine, follow the command with the --no-browser option. For example, <youtrack_home>\bin\youtrack.bat start --no-browser.
To view all the available command options, enter <youtrack_home>\bin\youtrack.bat help.
Continue with the upgrade in the web-based Configuration Wizard.
- If you have a browser installed on the host machine, the Configuration Wizard opens automatically.
- If you do not have a web browser installed on the host machine, open the URL of the wizard in a web browser on another workstation. The wizard URL is printed in the console output:
  JetBrains YouTrack <version> will be available on [<YouTrack Base URL>/bundle/starting?wizard_token=<value>] after start
In the Configuration Wizard, click Upgrade.
On the Select Upgrade Source page, click the Select button and select the backup file of your current database that you have created.
When done, click Next.
On the Confirm Settings page, confirm or change your system settings and the location of system directories.
Here you can also enable built-in TLS to secure the network connection for the server. If you want to apply this change during an upgrade installation, follow the instructions for switching to HTTPS during upgrade, starting from the step that tells you to switch to HTTPS.
Review your license. If required, you can also update your license on this page.
When done, click Upgrade.
- YouTrack launches its components.
  Do not close the page in the browser until the setup is complete.
- When the YouTrack Server server is ready, the Dashboard opens. Your YouTrack Server instance is upgraded and ready for use.

Last modified: 20 April 2024