Upgrade Procedures

Starting the Upgrade

After you’ve designed your upgrade plan, considered system performance, and assessed storage needs, there are a few basic steps to start the upgrade:

  1. Upgrade your existing version 2 instance to the latest available 2.x version as documented in Upgrading from 2.x to 2.y.
  2. If you have not already, install Nexus Repository Manager 3.
  3. Enable the upgrade capabilities in both version 2 and version 3.

With the above complete, you can use the upgrade tool in version 3, which guides you through upgrading in three phases:

  • Preparing: the phase that prepares the transfer and creation of all configuration and components.
  • Synchronizing: the phase that counts and processes all components set to upgrade and upgrades all other configurations.
  • Finishing: the phase that performs the final clean up then closes the process.

Enabling the Upgrade Capability in Version 2.x

In version 2, enable the Upgrade: Agent capability to open the connection for the upgrade-agent.

Follow these steps:

  1. Click to expand Administration in the left-hand panel.
  2. Click the Capabilities menu item to open the respective screen.
  3. Click the New button to access the Create new capability modal.
  4. Select Upgrade: Agent as your capability Type.
  5. Click Add to close the modal and add the capability.
  6. Copy and save the Access Token found on the Status tab for your new capability. You need it to configure the Upgrade tool in 
    version 3.

In the lower section of the Capabilities interface, the repository manager acknowledges the upgrade-agent as Active.

Enabling the Upgrade Capability in Version 3.x

In version 3, enable the Upgrade capability to open the connection for the upgrade-agent and access the Upgrade tool.

Follow these steps:

  1. Click Capabilities in the System section of the Administration main menu to open the Capabilities feature view.
  2. Click Create capability.
  3. Select Upgrade, then click Create capability to enable the upgrade capability.

Upgrading Content

After you enable the upgrade capabilities, access the upgrade tool in Nexus Repository Manager 3 to start your upgrade.

  1. Go to the Administration menu.
  2. Select Upgrade located in the System section of the Administration main menu to open the wizard.


The upgrade tool provides an overview of what is allowed for an upgrade as well as warnings on what cannot be upgraded.

Agent Connection

This screen presents three fields: URL, Access Token, and Fetch Size. In the URL field, enter the URL of your version 2 server including the context path e.g.  http://localhost:8081/nexus/ . In the Access Token field, enter the access token, copied from your version 2 Upgrade: Agent capability Status tab. The Fetch Size determines how many assets are transfered at once from the version 2 server to version 3; lowering the default value can mitigate memory or time out issues.


This screen allows you to select from Repository configuration and content, which includes user accounts and associated security settings, and Server configuration. Check the options that apply.

The Repository configuration and content upgrades all user accounts when selected. If certain user accounts aren’t desired in Nexus Repository Manager 3 then you can delete them from Nexus Repository Manager 3 after the upgrade for all repositories is done.

Repository Defaults

The Repository Defaults screen allows you to select the directory destination and transfer method. The first drop-down menu, Destination, allows you to pick a blob store name different from default. The second drop-down menu, Method, allows you to choose the transfer method. This section allows you to click and change each repository’s individual transfer method and destination (i.e. blob store).

Figure: Partial List of Repository Selections for Upgrade


If User-Managed Repositories is one of your selections from the Content screen, the Repositories screen allows you to select which repositories you want to upgrade. As shown in Figure: Partial List of Repository Selections for Upgrade, you can select all repositories with one click, at the top of the table. Alternatively, you can select each individual repository and customize upgrade options for each repository with the configuration icons in the last column. In addition to Repository, the table displays information about the status of the repository. Keep in mind that the Repository ID defined in version 2 is displayed in the list and after the upgrade used as the Name of the repository.


This table displays a preview of the content set for the upgrade, selected in the previous screens. Click Begin, then confirm from the modal, that you want to start the upgrade process.

Running the Upgrade

After the upgrade was started in the Preview screen, the repository manager starts with a short Preparing step. From this point on, no further configuration changes should be performed on version 2. They will not be moved to version 3.

Any upgrade process invoked destroys any existing configuration in the target Nexus Repository Manager 3 server and replaces it with the upgraded configuration from version 2.

However, any content changes to the upgraded repositories continue to be upgraded during the following Synchronizing step. For example, new proxied components or new deployed components in version 2 are transferred to version 3.

During the transfer process, your content can already be viewed and accessed in version 3, for example via using the component search or browsing in repositories or repository groups. However, the repositories will be offline until the process is fully complete.

The status in the view shows the number of components transferred and when the last changes were detected in version 2. Once all components are migrated and no further changes have been detected for a while the upgrade is mostly complete. You can now decide upon waiting for further deployments (and component evaluations in the case of Nexus Firewall) to version 2 or finalizing the upgrade. To finalize, stop the monitoring and proceed through the Finishing screen.

After the Upgrade

With the upgrade completed and all components transferred, you can perform the next steps in your upgrade plan. These can include:

  • Rebuilding search indexes and browse nodes
  • Stopping Nexus Repository Manager 2.
  • Archiving Nexus Repository Manager 2 and delete the install from the server.
  • Reconfiguring Nexus Repository Manager 3 to use the HTTP port, context path, and repository paths of version 2, if desired.
  • Alternatively updating all tool configurations pointing to the repository manager, such as Maven settings files and POM files.

Rebuild Search Indexes and Browse Nodes 

NEW IN 3.36.0

After migration, the Repair - Rebuild repository browse and Repair - Rebuild repository search tasks must run in order to build search indexes and browse nodes.

If necessary, you can modify this behavior:

If you set nexus.migration.search.buildDuringMigration=true in the <data-dir>/etc/nexus.properties  file, Nexus Repository will build the search indexes during the final migration step, which will not complete until this step is accomplished. No task will launch. 

if you set nexus.migration.browse.buildDuringMigration=true in the <data-dir>/etc/nexus.properties file, Nexus Repository will build the browse nodes during content migration and will not launch the task at completion.

Configuring Legacy URL Paths

By default, Nexus Repository Manager 2 uses a different URL pattern to expose repositories and repository groups than Nexus Repository Manager 3. During upgrade from NXRM 2 to NXRM 3, a capability is added so that Nexus Repository Manager 3 automatically supports the old patterns and your automated tools and CI continue to work. This allows the example of  http://localhost:8081/nexus/repository/sample  to also be accessed using  http://localhost:8081/nexus/content/repositories/sample .


This example assumes your hostname ( localhost ), port ( 8081 ) and context path ( nexus ) match between your Nexus Repository Manager 2 and Nexus Repository Manager 3 installations. If not, you must utilize the ones from version 3 or reconfigure as stated in Changing the Context Path section.

This capability has no effect on REST API calls because these were totally rewritten in NXRM3. Any REST API calls need to be reevaluated and rewritten against the NXRM3 REST API.

Pre 3.7, if you want the old URL format, you must make a configuration change.  This can be done in $data-dir/nexus3/etc/nexus.properties by adding:


Restart the application for the change to take effect.

Any automated tooling that uses direct repository browsing will not function in Nexus Repository Manager 3 as that is not currently supported.

Restarting an Upgrade Process

If you are running a Nexus Repository Manager 2 to 3 upgrade and it needs to be restarted for some reason (the upgrade was canceled, or a problem occurred) it will be necessary to start the upgrade over from the beginning. 

Resetting An Upgrade To Repository 3 from Repository 2

  1. Use the Abort or Cancel buttons in the upgrade wizard in Repository 3 if available to you, to end the migration process explicitly.
    Complete all remaining steps regardless of whether you have this option or this option cannot be completed.
  2. Shut down Repository 3 and remove the entire Repository 3  $data-dir  directory.
  3. Shut down Repository 2 and remove the entire Repository 2 directory at $work-dir/db/migrationagent  .
  4. After Repository 2 is restarted, go to Administration → Capabilities.
    Select the Upgrade: Agent capability and then click the Delete button to remove the Upgrade: Agent capability.

    This step will remove any internal RepositoryMigrationTask scheduled tasks that pertain to repository migration. These tasks will not be visible in the Scheduled Tasks view to an administrator so this is the only way to remove these if they remain.