Skip to main content

Prerequisites for Upgrading from Nexus Repository 2 to Nexus Repository 3

A successful upgrade from Nexus Repository 2 to Nexus Repository 3 requires planning, decision making, and, if possible, testing before attempting the actual upgrade.




Nexus Repository 2 instance is on the latest Nexus Repository 2 version


Your Nexus Repository 2 instance must be on the latest Nexus Repository 2 version before upgrading to the latest Nexus Repository 3 version.

Upgrading to an older Nexus Repository 3 then subsequently updating to the latest Nexus Repository 3 is not equivalent, as it will hit old upgrade bugs.

Both Nexus Repository 2 and Nexus Repository 3 have the same license type (OSS or Pro)


When upgrading from Nexus Repository 2 to 3, both versions must have the same licensing setup.

The same license file can be used in Nexus Repository 2 and Nexus Repository 3 or a license can always be applied at a later time.

If the Nexus Repository 3 instance is on the same server as the Nexus Repository 2 instance, both instances will automatically share the same license. Otherwise, you will need to install the license on the new Nexus Repository 3 instance.

The Nexus Repository 3 instance must not yet be in use; it must be a fresh/clean instance


The upgrade tool completely replaces existing configurations in Nexus Repository 3. It is intended for one-time use, and if you need to re-start an upgrade, you must first reset that upgrade.

All files in the Nexus Repository work directory must be owned by the OS user, and there should be no zero length files in the work directory


You can use the following Linux command to find files in the work directory that are not owned by the 'nexus' user as well as zero length files:

find . \! -user nexus -print

Decide on a data transfer method; ensure you have adequate storage space for the upgrade


Full details available in Deciding on a Data Transfer Method.

Ensure Nexus Repository 2 repository and repository group Repository IDs differ by more than just case. You must use distinguishable names.


IDs of repositories and repository groups in Nexus Repository 2 that differ only by case will not be accepted during an upgrade to Nexus Repository 3 (example version 2 IDs: myrepoid vs. Myrepoid).

Ensure your Nexus Repository 3 instance is using an external PostgreSQL database PRO


We highly recommend that you set up your Nexus Repository 3 instance with an external PostgreSQL database. See our documentation on configuring Nexus Repository Pro for an external PostgreSQL database.

Review repository groups' contents in Nexus Repository Manager 2 to ensure all contents are selected for upgrade.


Neglecting to select a single repository within a group may prevent the entire group from being upgraded.

If necessary, configure your blob stores in Nexus Repository 3. (See our Storage Guide)


You will not be able to make configuration changes in Nexus Repository 3 again until the upgrade has successfully completed.

If you wish to use and move user tokens, navigate to the User Token tab in the Administration menu on the Nexus Repository 2 instance and check to ensure that user tokens are enabled.


The upgrade tool only upgrades pre-existing user tokens to Nexus Repository 3 if user token support is enabled in Nexus Repository 2.

Consider optimizing upgrade performance by disabling unnecessary tasks and enabling some helfup ones.


Full details available in the Optimizing Upgrade Performance topic.

Back up your infrastructure


Establish a safe recovery point should something go wrong.

Test your upgrade with your desired upgrade settings using a similar test environment


As a best practice, we recommend trying to create a test version of your current production environment so that you can test upgrading from Nexus Repository 2 to 3 there before performing it in a production environment. This can help you see what errors (such as out of memory errors in Nexus Repository 2) may occur with your selected test upgrade settings. Then, you can adjust your settings so that you do not encounter these errors when upgrading your production instance.