Upgrading Xray

JFrog Installation & Setup Documentation

Content Type
Installation & Setup

Subscription Information

This feature is supported on the Self-Hosted platform, with Pro X, Enterprise X, and Enterprise+ licenses.

The procedure to upgrade Xray depends on your installation type. We strongly recommend reading through this page before proceeding with your upgrade.


Make sure to use the same upgrade method (RPM, Debian, Docker, etc.) as the one you initially used to install Xray.

Before you upgrade Xray please refer to additional information on system requirements (for storage, databases, browsers and other requirements), and the system architecture.

Xray 3.x and 2.x support PostgreSQL versions 9.5, 9.6, 10, 11, 12 (the earliest version of Xray 2.x that supports PostgreSQL 10-12 is Xray 2.16). Xray 3.x supports PostgreSQL 13,14, and 15. Because PostgreSQL has ended its support for some of its older versions, including 9.5 in February 2021 and 9.6 in November 2021. Although it is possible to upgrade incrementally from 9.5 to 9.6, JFrog recommends upgrading to PostgreSQL 15. This will extend the time until the next PostgreSQL end of support and enables Xray to take advantage of the latest abilities provided by the new versions, such as better performance.

To learn about the process and requirements for upgrading PostgreSQL, see JFrog Xray PostgreSQL Upgrade - PostgreSQL 9.x EoS.

Xray supports high availability (HA) and hot upgrade of HA installations from version 3.31.0. For more information on HA upgrade, see HA Upgrade.

Upgrading from Xray 2.x to the latest version of Xray

Starting from version Xray 3.88.10, you can no longer upgrade Xray 2.x directly to the latest version of Xray. You must upgrade from Xray 2.x to 3.87.x, and then upgrade to the latest version of Xray.

Do you have more than one Artifactory instance connect to your single Xray instance?


Applicable for upgrade from Xray 2.x

When upgrading to the JFrog Platform, Xray must be connected only to a single Artifactory instance. If you have one Xray instance connected to more than one Artifactory instances, use one of the following options before proceeding with any upgrade.

  • Option 1 (recommended): Keep one connected Artifactory instance to your single Xray instance, and upgrade the rest to version 7.x with newly installed Xray version 3.x instances. This option will require re-indexing the the additional Artifactory instances, and will cause some loss of configuration data.

  • Option 2: Install additional Xray version 2.x instances for each Artifactory instance that you have, and restore all MongoDB and PostgreSQL data. Continue to upgrade each Artifactory and Xray pairs to version 7.x and version 3.x. This procedure is only suggested if you must keep all your Xray configurations and easily reconfigure them in the new instances

Upgrade Steps

Before You Proceed

To ensure you can restore your Xray and database in case you encounter any issues during the upgrade process, we strongly recommend you make sure your system and database backups are up to date.

From version 3.x, MongoDB will not be used by Xray except during the initial migration phase from version 2.x. The data will be automatically migrated from MongoDB to PostgreSQL. Make sure your PostgreSQL storage size is increased by at least 2.5 times than its current size.

The upgrade procedure involves the following steps:

  1. Download Xray (Docker Compose, RPM, Debian).

  2. Stop the Xray service

  3. Install Xray according to the distribution type.

  4. Check the Migration Log and review system.yaml to validate the migration was successful (only for upgrading from v3.x).

  5. Start the service using the start scripts or OS service management.

  6. Check the Xray Log for the status of the service.

Default Home Directory / $JFROG_HOME

The default Xray home directory is defined according to the installation type. For additional details see the Product Directory Structure page.

Note: This guide uses $JFROG_HOME to represent the JFrog root directory containing the deployed product.