Migrating to Nexus Repository 3 – Easy Peasy

Migrating to Nexus Repository 3 - Featured Image

Migrating to Nexus Repository Manager 3 - Video

Nexus Repository Manager 3 is released and available to everyone as the free OSS distribution. With the increased support for different repository formats and numerous other advantages, we’ve got thousands of new users adopting it.

Users of Nexus Repository Manager 2 might be interested to know how to upgrade and take advantage of the new version.

Of course you can install version 3 on a new server or even the same server and run it in parallel. This gives you access to the new repository formats and features without interrupting your tested and proven Nexus Repository Manager 2 deployment.  Ultimately however, nobody wants to support multiple versions of any software. Just ask any web developer about supporting different versions of IE.

Good thing we got you covered! Our upcoming 2.14 and 3.1 releases includes a migration tool that makes it dead simple for everyone to get all their setup and content from Nexus Repository Manager 2 into a new Nexus Repository Manager 3 installation. In addition 3.1 includes a number of other great features such as PyPi support and Content Selectors. But I can tell more about that another time – today we are going to look at migration.


So what can you expect from the migration?

  • Nearly all your content and configuration can be moved
  • It is easy
  • No downtime is needed
  • Client tools like Maven, Jenkins, npm or NuGet do not need to be reconfigured

There is really nothing to worry about.

Step by Step

Let’s see how you would go about the migration step-by-step. This will give you a good idea and by the time we are releasing 3.1 the documentation will be updated and cover all aspects of a migration in a dedicated chapter in detail.

There are only a few steps necessary to get ready and start the migration:

  1. Upgrade Nexus Repository to latest 2.14 and configure the included migration capability that allows you to sync from version 2 to version 3.
  2. Install Nexus Repository 3.1 on the same server, ensure it runs on a different port and start it up
  3. Configure and start the migration

The migration process is  managed in a user -friendly wizard that guides you through the process. First you get to select, what  configuration and content you want to migrate.

Migration from Nexus Repository 2 to Nexus Repository 3

And then specifically which repositories to transfer. Different options allow you to improve performance and disk space usage during the migration.

Migration from Nexus Repository 2 to Nexus Repository 3

When you have finished selecting what you want to migrate you are off to the races. Finish up and go!

Migration from Nexus Repository 2 to Nexus Repository 3

And lean back and watch its churn on the transfers.

Migration from Nexus Repository 2 to Nexus Repository 3

Until it is finished.

That’s already it. During migration Nexus Repository Manager 2 will continue to work as before, any additional proxied or hosted components are continuously included in the running  synchronization. You can keep it running for a while and prepare to get that to make the final move.

Final Switch

This last flip over is  performed with a few easy steps that you can all get done in a few minutes.

  1. Finalize migration in Nexus Repository Manager 3
  2. Shutdown Nexus Repository Manager 2
  3. Shutdown Nexus Repository Manager 3
  4. Reconfigure it to run on the original port and context of Nexus Repository Manager 2, for example port 8081 and /nexus context.
  5. Start Nexus Repository Manager 3

Congratulations – you are done. Depending on your specific setup e.g. usage of an external reverse proxy server around the repository manager the detailed config steps will vary a little bit, but the general approach is the same.

All external settings.xml, .npmrc and similar config files using repository URLs such as http://repository.example.com:8081/nexus/content/groups/public will continue to work in Nexus Repository 3, so you wont have to reconfigure any client tools.

Next Steps

With the migration completed you can explore your shiny new Nexus Repository Manager and move the needle further:

How about starting to use Docker and the support for private registries as well as proxying DockerHub and other registries?

Or if you are more into client-side JavaScript you could add Bower repositories to the mix?

Now that you are on version 3 you will be able to access all these new features and gain access to coming features like high availability easily.

And if you have a lot of automation with the Nexus Repository Manager planned, you should chime in again soon. Next time I will show you how you can use the REST and Integration API to script for the creation of repositories and a whole lot of other tasks.

The following two tabs change content below.

Manfred Moser

Manfred Moser is trainer, author and community advocate at Sonatype working on efforts around the Nexus Repository Manager, the Nexus IQ Server and the Central Repository. He is a regular speaker at conference such as JavaOne, AnDevCon, OSCON and others.. Fluent in both German and English, he also speaks and writes Java and a bunch of other programming languages and uses these skills as committer and project lead on a number of open source projects such as the Android Maven Plugin. The open source community and open source software has been a passion of his for well over a decade and he is sure it will be for a few more decades. Manfred can be found on most social channels, including Twitter, LinkedIn and Google+.

Related posts


    • Bart said:

      Our ‘upcoming’ 2.14 and 3.1 releases includes a migration tool that makes it dead simple for everyone to get all their setup and content from Nexus Repository Manager 2 into a new Nexus Repository Manager 3 installation.

      The keyword here is ‘upcoming’…as in…not yet there… 😉

  1. Hector said:


    What I would like to know is how i can introduce my own repositories in Nexus 3.0 so that I can migrate the internal Architectures and dependencies of my repository.

    Best regars

  2. Gordon said:

    It’s been nearly two months with no news on Maven support for NX3, let alone migration. Any chance of an ETA?

    • Manfred Moser said:

      Maven support has been in 3.x since the beginning. It is totally suitable for most use cases. However it is not yet equivalent in features to 2.x. 3.2 later this year will catch up on some of that, but again.. you can totally use it today and it works just fine.

  3. Christophe LARCHER said:

    We deployed a NEXUS 3 ans we still wait the migration process to be released ….to migrate our MAVEN NEXUS 2 repositories.
    We have no news about this subject….for so long…
    What’s going on ?

      • Michal Margiel said:

        Any update on the 2.14 release? We have now extremely late July 2016 😉

      • Simon Fraser said:

        July ’16 has been and gone; any update on when it might happen? We have a number of tasks that we’ll be able to do more efficiently with Nexus 3, but it would be good to know whether it’s better to just cut our losses and get them done with the existing repo.

  4. ryan.kong said:

    why 3.x UI not provider the category browse service like 2.x

  5. Aswini Rajasekaran said:

    Can you tell me what features of maven repositories are missing in 3.0 version of Nexus?

  6. rgoers said:

    This is just strange. I can download Nexus 3.0 but the documentation practically tells me not to use it. Instead I should wait for 3.1 which seems to have a pretty vague release date. (As of today Jira shows it 30 days overdue with 13 issues yet to complete). Comments above say that 3.0 isn’t on par with 2.x and that 3.2 will catch it up? So should we just continue with 2.x and ignore 3.x until at least 3.2?

  7. Bruce Smith said:


    I have to do a migration soon, any idea when this will be available?

    Thank You,
    Bruce Smith

  8. dan russell said:

    Any idea of when 2.14 and 3.1 are likely to be available now july has been and gone?

  9. Olga Maier said:

    Hi, I’ve a question about migration Nexus Repository. How can I migrate the repositories from old server with the Nexus Version 2.13.0-01 to the New Nexus Server with the version 3.0.1-01. Do you have some experience or ideas?

  10. Pavan Kumar said:


    Nexus is installed in windows server 2008R PC, now we are planning to upgrade the windows server to windows 2012.
    The question is whether the nexus supports windows server 2012 or not ?. Please let me know if is there any version dependencies with windows server 2012.

  11. ryan said:

    Contrary to the last paragraph of “final step” and per the documentation if you need legacy /content/groups/…. URLs to work you must configure legacy mode by placing this line in nexus.properties: org.sonatype.nexus.repository.httpbridge.internal.HttpBridgeModule.legacy=true

  12. Yves Schumann said:


    I’ve tried the update of our 2.14.1-01 instance to 3.1.0-04. Unfortunately the update is far away from “easy peasy”! It might work if you have only a bunch of artifacts on your repository but with a real huge on, actually no way. :-(

    In our Nexus2 instance there are round about 250 repositories (2/3rd hosted, 1/3rd groups), 300.000 artifacts and 350G of data. OK, much data will take some time to migrate. I’ve waited around 4 (!) hours to analyze one (!) of the hosted repositories and here comes the first bad thing: You need to stay in front of the browser to click something at least every 15 minutes before your session expires. If you miss this, the migration fails. The next bad thing: The partly migrated repo is broken und cannot be deleted! I’m always running into some kind of an timeout error. Tried this multiple times now, always with a completely new setup but different repositories.

    So here’s the Go-NoGo-Question: How can I fix (or remove) broken repos? I’ve seen, that there are no longer real files on the harddisc instead of “blobs”! So now one is absolutely lost if something goes wrong. How can I let the migration run unattended?

    Some details from the background:
    Both Nexus instances are Docker containers, each with separate storage. So the migration must copy the data from the storage of one container to the storage of the other one.

    Kind regards,

  13. Christian Goetze said:

    We have a huge private repository. Does the migration create a full copy of the repository? It would be great if it used hard links for the actual artifacts…

    • Yves Schumann said:

      Using hardlinks is an option during configuration of migration, so this might work as you wish (haven’t used this by myself).

  14. Steve Boardwell said:

    is it possible to run both Nexus 2 and Nexus 3 side-by-side? It sounds from the post like it’s possible.
    We currently need Nexus 2 for the yum repository support, and Nexus 3 for the docker registry, npm.
    We would be installing from scratch but I’d like to know if there are any pitfalls to look out for.

    * are there any ports apart from the web-server that need to be configured differently?
    * we would install in separate directories but are there any system folders to be aware of (log naiming, etc)?

    Do you perhaps know when Nexus 3 is to receive yum support?

    Thanks for any help you can offer.

  15. Erik Brakkee said:

    I migrated a ckmpang nexus from 2.14 to 3.1 and found out that the repository URLs have changed. Specifically, content/groups has changed into ‘repository’. Very annoyjng because I now have to try to fix it using URL rewriting in apache. I also filed a bug about this. See https://issues.sonatype.org/browse/NEXUS-11871

    • Erik Brakkee said:

      Update:it appears the old nexus 2 urls are still supported but it requires adfitional configuration.

  16. Rajeev said:

    Hi @all,
    We have Nexus2 and Nexus3 running on different Linux servers. Is there a way, where I should be able to migrate only a handful repositories and not the entire set up? We have some private repositories that we want to migrate from nexus2 to nexus3. When I used the migration utility, it overlaid the entire nexus2 over nexus3 installation and made the nexus3 unusable.
    Please let me know if there is a way to migrate only a few private repositories from nexus2 to nexus3 when they both are running on different servers.

  17. Michael said:

    I have installed the Version 2.14.2 (oss) and 3.2.0 (oss), but i can’t find the included migration capability.
    It’s this not included in the oss-version?
    It’s possible to add this migration tool?

    Thank’s for help

  18. Danilo Ischiavolini Chaves said:


    I’ve migrated the nexus 2 to nexus 3, but the repository change the path (nexus/content/groups/public) “Nexus2” to (nexus/repository/maven-public) “Nexus 3”,

    There is any configuration that i need to do for this works?

    Good Article..


  19. Dan said:

    Have you seen this issue before? javax.ws.rs.ProcessingException: com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field “productEdition” (class com.sonatype.nexus.migration.client.StatusClient$StatusXO), not marked as ignorable (4 known properties: “protocol”, “enabled”, “metaClass”, “product”]) at [Source: java.io.BufferedInputStream@1231ecd6; line: 4, column: 23] (through reference chain: com.sonatype.nexus.migration.client.StatusXO[“productEdition”])

  20. Robbert said:


    We have Nexus Pro with more than 4TB repository datastorage (Windows). Due to its size we use multiple volumes. How will the migration tool handle this?. We would setup a new Nexus 3 server on Linux but can we f.e. specify seperate volumes and/or blobstores for the release repositories during migration ?.


  21. Jon said:

    Is there any way to rate-limit the migration? It’s killing our Nexus 2 server every time we attempt the migration. The Nexus 2 server gets pegged at 100% CPU and nobody can use it.

  22. Bashar Hoque said:

    Good post Manfred. I attempted the upgrade (2.4.3-02 to 3.2.1-01) in our non-production nexus repo which has about 5.9gb of artifacts. I have configured nexus3 to use a separate data folder than nexus2 data folder. After migration the data folder for nexus3 shows only 313mb of space used. Where did all 5.9gb of data get transferred to from nexus2 to nexus3?


  23. msd said:

    I am getting below error while migrating nexus from 2.14.3-02 to Nexus 3.1.0-04 after Next in the Agent connection tab of Nexus 3.

    javax.ws.rs.ProcessingException: com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field “productEdition” (class com.sonatype.nexus.migration.client.StatusClient$StatusXO), not marked as ignorable (4 known properties: “protocol”, “enabled”, “metaClass”, “product”]) at [Source: java.io.BufferedInputStream@51a09135; line: 4, column: 23] (through reference chain: com.sonatype.nexus.migration.client.StatusXO[“productEdition”])