Skip to main content

Moving From NuGet Version 2 to NuGet Version 3

About NuGet Version 3

As you may know from our blog, NuGet introduced a newer, more scalable version of its protocol based on JSON instead of XML. The newer NuGet version 3 protocol allows you to store package details in a static JSON format and is designed to scale more easily.

In Nexus Repository, NuGet version 3 repositories end with/index.json; version 2 files do not end with/index.json.

For example, if you have a V3 repository called nuget-v3 and want to use version 3, your repository URL may be http://localhost:8081/repository/nuget-v3 while the NuGet source will be http://localhost:8081/repository/nuget-v3/index.json (Repository URL + /index.json).

By default when NuGet sees that the source ends with ".json," it expects that the source URL points to the service index and runs all calls using the version 3 API.

Migrating from Version 2 to Version 3

It is not possible to just modify version 2 group or proxy repositories and turn them into version 3 repositories. You will need to follow the migration steps below to fully migrate to version 3.

Repository Type

Migration Steps


NuGet Hosted

No migration needed; NuGet hosted repositories support both NuGet v2 and v3 protocols

Acts as version 2 or version 3

NuGet Group

  1. Create new NuGet version 3 group member repositories

  2. Create a new NuGet version 3 group repository

  3. Add members to the group

New version 3 group containing version 3 members

NuGet Proxy Repository

  1. Create new version 3 proxy repository

  2. (Optional) If you wish to retain your packages from your version 2 repository, migrate packages by exporting version 2 proxy packages and import to a new version 3 hosted repository

  3. (Optional) If desired, create a version 3 group repository containing a new version 3 proxy repository and your version 3 hosted repository that contains your version 2 proxy packages

Possible Outcome 1: New version 3 proxy repository

Possible Outcome 2: New version 3 hosted repository containing packages from the version 2 proxy repository

Potentially a new version 3 group repository containing a version 3 proxy repository and the version 3 hosted repository with the version 2 packages

To better explain how to migrate from Version 2 to Version 3, let's follow an example of migrating a version 2 proxy repository:

Let's say you have a NuGet version 2 proxy repository callednuget-v2-proxyand a NuGet source callednxrm-proxy.

Your NuGet source is currentlyhttp://localhost:8081/repository/nuget-v2-proxy.

For you to move to the NuGet version 3 API, you will complete the following steps without making changes to your version 2 repositories:

  1. Create new NuGet version 3 proxy repository.

  2. Change the NuGet source to http://localhost:8081/repository/nuget-v3-proxy/index.json (Repository URL + /index.json).

At this point, if you do not wish to retain your proxy repository version 2 packages, you are done.

If you do wish to retain your version 2 packages, you can proceed to Migrating Packages from Version 2 Repositories.