Upgrading from Nexus Repository Manager 2

Upgrading Nexus Repository Manager presents a necessary step to gain access to new features, bug fixes, performance improvements and other advantages. Regular updates to the latest release are recommended as a general best practice.

Specifically Nexus Repository Manager 3 represents a shift in design that supports a wider set of features requested by customers as well as a platform for a modern, expanded set of functionality. Given these changes, many to the core architecture, the upgrade process requires more attention than in previous versions.

This section covers upgrades of Nexus Repository Manager in general with a focus on upgrading Nexus Repository Manager version 2 to Nexus Repository Manager version 3. The general process of upgrading depends on the specific usage of the repository manager, its configuration and integration with other tools and is potentially complex. Further resources can be found in the Support Knowledge Base.

Nexus Repository Manager Pro customers can take advantage of the assistance of the support team.

Why Upgrade to Nexus Repository Manager 3?

In Nexus Repository Manager 3, there is wider feature and functionality equivalency to Nexus Repository Manager 2. Highlights of new functionality include:

  • Expanded repository format support
  • Improved user interface
  • Powerful component search
  • Universal repository browsing
  • Enhanced metadata

Of course, the choice to upgrade depends on the features your team is using and planning to use. In many cases upgrading to version 3 provides an enhanced set of features to support modern development practices and automation. However, it is a good idea to review supported formats, version 2 to 3 feature equivalency and the feature matrix to make sure all needs are fulfilled.


Upgrading Nexus Repository Manager 2 to 3 only provides native tooling to transfer content and configurations from the respective source repository manager to the target repository manager. We strongly discourage you to run the upgrade from version 2 to version 3 while simultaneously running any data center-to-data center transfers (e.g. synchronizing applications in your cloud server to on-premises data centers or vice-versa).

Upgrading from 2.x to 2.y

At a high level, upgrading from a 2.x release of Nexus Repository Manager to a newer 2.y version typically includes:

  • Extracting the new release bundle
  • Replicating configuration changes
  • Stopping 2.x instance
  • Replacing the application directory with the new instance
  • Starting the new instance

Full instructions are available on the support site.

Upgrading from 2.x to 3.y

Upgrade should be done using only the latest 2.x and 3.y to assure that any fixes in the upgrade process are utilized when upgrading. The latest Nexus Repository Manager versions are verified as compatible before deployment.  The first step in upgrading from Nexus Repository Manager 2 to 3 should be upgrading to the latest 2.x version. Only after this has been done should upgrade be attempted.

Upgrading from Nexus Repository Manager 2 to 3 requires you to be on the same licensed model of the product on both servers.  Thus Nexus Repository Manager 2 OSS users should upgrade to Nexus Repository Manager 3 OSS and Nexus Repository Manager 2 PRO users should upgrade to Nexus Repository Manager 3 PRO.  The same license file can be used for both instances.  PRO users who have questions about their licensing can ask their Customer Success representative or file a support ticket.

Upgrading from Nexus Repository Manager 2 to 3 also requires the involved repository managers to use a compatible version of Nexus Repository Manager 2 and 3. If the source repository manager uses a version prior to 2.14.1, you must upgrade it as detailed in Upgrading from 2.x to 2.y before starting the upgrade to Nexus Repository Manager 3. The target repository manager is typically a fresh installation with a minimum release version of 3.1. If an existing Nexus Repository Manager 3 is used as the target, it has to be upgraded to 3.1 (or later) as documented in Upgrading.

Using an existing installation of Nexus Repository Manager 3 populated with data and configuration as the target repository manager is not supported. The upgrade should be done against a new Nexus Repository Manager 3 installation (a single node, not HA) that does not contain existing configuration. Note that this means the upgrade must be done in one shot, running the upgrade multiple times is not supported.

If you must upgrade using an older version of Nexus Repository Manager 2, against the recommendations of Sonatype, see the compatibility matrix to make sure you upgrade to the correct associated version. Upgrading using non-associated versions will result in errors. Also remember, only versions 2.14.1 and beyond can be upgraded to Nexus Repository Manager 3.

The following topics in this section go into Upgrading from 2.x to 3.y in more detail: