Upgrading Xray

JFrog Installation & Setup Documentation


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.

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). 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 13. 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.


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

Xray with Artifactory 7.41.4 and 7.41.6

If you install/upgrade to Xray 3.55.0 and above while using Artifactory 7.41.4 and 7.41.6, the Xray tabs in the UI disappears. However, Xray functionality continues to work as expected. The issue was resolved in Artifactory 7.41.7 and later.

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

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. Learn More >

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. Learn More >

RabbitMQ Upgrade to version 3.11.x and later

Xray version 3.70.0 and later includes RabbitMQ version 3.11.x later. An upgrade to Rabbit MQ 3.11.x requires feature flags to be enabled. For more information, refer to Required Feature Flags in RabbitMQ 3.11.0.

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.