Skip to main content

Manual Upgrade Methods

When either upgrading to a new Nexus Repository 3 instance or consolidating to an existing instance, you can manually upgrade repository content into Nexus Repository 3 Pro using any of the following methods:

  • Using the Repository Export/Import features

  • Including external proxies in a group repository

  • Running scripts using the REST API

Manual upgrade methods have a few considerations:

  • Expect to spend a fair amount of time in planning and executing any upgrade

  • You cannot import or export repository configuration

  • Some data duplication is required


Before proceeding with any upgrade, we recommend taking the following steps:




Access to Repository Storage


  • You must export content to a folder that the Nexus Repository 3 instance can access.

  • You can only import content from a folder that the Nexus Repository 3 instance can access.

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 or on migrating an existing Nexus Repository 3 instance to a PostgreSQL database.

Back Up Infrastructure


Do a Test Run


  • Do a test run of the import process to identify issues and approximately how long the process could take.

Use Import Hard Links


  • Hard linking is far faster and does not duplicate the data on disk.

  • Review the Import Hard Links documentation for details.

Avoid Importing Directly to S3


  • Use File-based blob stores when possible.

    • Importing directly to an S3 blob store can be 3x slower.

  • Use the move blob store functionality to migrate to S3.

Firewall Repositories


  • You cannot migrate Firewall waivers.

  • Prefetch the approved components through the proxy before enabling the Firewall quarantine.

  • Export the Firewall report to obtain a list of approved components.

Export/Import Manual Upgrade Method PRO

Using Repository Export and Repository Import (both Pro-only) is the easiest and fastest manual method to copy a repository's contents from one Nexus Repository 3 instance to another.


  • You can directly import Nexus Repository 2 repository content from where it is stored on disk.

  • The import task will maintain the created date, last updated date, and the last downloaded date attributes from Nexus Repository 2.

  • In cases where the content in the source directory changes or the process is interrupted, you can use these tasks to only add the missing/additional content.

  • The tasks must be manually created; you cannot use scripts or the API.

  • You will need to create and run individual tasks for each repository.

  • Multiple tasks will not run at the same time.

Steps for Nexus Repository 2 to 3 Export/Import Upgrade

  1. Ensure that your Nexus Repository 3 instance has file system access to the Nexus Repository 2 storage; consider using a backup if Nexus Repository 2 is located on a different server.

  2. On your Nexus Repository 3 instance, create the target repository to which the content will be imported.


    As a best practice, ensure that the blobstore for the target repository is on the same storage as the source repository; this will allow you to use hard linking (recommended).

  3. Under AdministrationSystemTasks on the Nexus Repository 3 instance, create a new Repository - Import external files task.

    1. Set the source directory to the folder where the Nexus Repository 2 repository is stored.

    2. Optionally, select Enable Hard Links (Recommended).

  4. Run the task.

    1. For testing, you may stop the task before it completes.

    2. Review the importing documentation on how to reset the import process.

  5. When finished use the Move Blob Store steps to use a different storage disk or S3 object store


If you have a lot of data to copy into the repository, this upgrade may take some time. Consider using the Proxying Repositories method below to make the source content available while waiting for the import tasks to complete.

Proxying Repositories Manual Upgrade Method

One common use case for proxy repositories is to use them to make content immediately available on a new Nexus Repository instance while slowly moving content as it is requested.


  • This upgrade will only copy content that is actively being requested by development and production. This may be an effective way to avoid moving unused content.

  • Nexus Repository fetches imported components through the proxy over HTTP(S), which can be very slow.

  • You will need to maintain both repository instances until your new instance contains all needed content.

  • You cannot convert a proxy repository to a hosted repository when the process is complete.

Steps for the Proxying Repositories Manual Upgrade Method

This method involves creating a proxy repository (called target-proxy in the example below) on the new Nexus Repository 3 instance and having that proxy repository use the URL of hosted repository on a source instance (called source-hosted in the example below).

When a component is requested from but not found on the target repository group (called request-endpoint in the example below), Nexus Repository downloads the component from the hosted repository on the source instance through the proxy repository. This is demonstrated in the diagram below:


This configuration can be used until the upgrade is complete.