---
updatedAt: 2026-10-07T06:34:36.000Z
agentTools:
siteIndex: https://docs.jfrog.com/llms.txt
projectIndex: https://docs.jfrog.com/artifactory/llms.txt
---
# Migration Tool
Migrate existing NuGet repositories to a normalized layout in Artifactory.
**Note**
As of JFrog Artifactory SaaS 7.152.1, you can use the Migration Tool to normalize NuGet repositories. Other migration types may be available in future releases.
The Migration Tool migrates existing NuGet local, remote, smart remote, and virtual repositories to a normalized layout. You can set Enforce Layout only when you create a repository. Use the Migration Tool for repositories that were created without Enforce Layout. For more information, see [NuGet Enforce Layout](/docs/nuget-repositories#nuget-enforce-layout-enabling-packagebaseaddress-api).
After you select a repository to migrate, the Migration Tool completes a dry run. For local and remote repositories, the report identifies compliant and non-compliant packages. For smart remote repositories, the report shows whether the origin repository is already migrated. For virtual repositories, the report identifies normalized and non-normalized included repositories.
When you migrate a local repository, you can designate a repository to store remaining non-compliant packages for later cleanup. Remote and smart remote migrations don't isolate packages. Virtual repositories don't store packages and don't require an isolation repository.
**Warning**
When a migration is in progress, the repository is unavailable for all developer interaction, CI pipelines, and virtual repositories. Pipelines and builds that rely on the repository will fail until the migration is complete.
For migrations that isolate packages, Artifactory moves non-compliant packages from the migrated repository to the repository you selected.
**Requirements:**
* Admin or Project Admin permissions
This topic covers the following tasks:
* [Migrate a Local Repository](#migrate-a-local-repository)
* [Migrate a Remote Repository](#migrate-a-remote-repository)
* [Migrate a Smart Remote Repository](#migrate-a-smart-remote-repository)
* [Migrate a Virtual Repository](#migrate-a-virtual-repository)
## Migrate a Local Repository
When you migrate a local repository, Artifactory checks all packages in the repository for compliance with the new normalization standards. If non-compliant packages are found, you can either manually fix the packages or choose to isolate them in a different repository before migration.
**To migrate a local repository:**
1. In the **Administration** module, go to **Artifactory Settings** > **Migration Tool**. The migrations table opens.
2. Click **Create Migration**. The migration wizard opens.
3. In the **Select repository** step, select a source repository from the list.\
The list only includes repositories of the relevant package type that are not already associated with another migration.
4. Click **Save and continue to dry run**. The migration is saved and starts a dry run to check the status of packages in the repository.
**Note**
The dry run may take some time to complete. You can navigate away from the migration page and access it again later from the **Actions** menu in the migrations table.
5. Once the dry run has completed, on the **Dry run results** step, review **Total Packages**, **Normalized**, and **Failed Normalization**.
**Normalized** is the number of packages that already follow the normalization rules and will migrate successfully. **Failed Normalization** is the number of packages that do not follow those rules. During migration, you can move the packages that failed normalization to an isolation repository. For the version rules, see [Understanding Normalized Versions](#understanding-normalized-versions).
6. Click **Download Report** to view a complete list of which packages will migrate successfully and which packages are non-compliant with the new normalization. Optionally, use this information to manually fix packages. To repeat the dry run, return to the **Select repository** step and click **Save and continue to dry run** again.
7. When you are satisfied with the state of the packages in the source repository, click **Set up migration**.
8. On the **Finalize migration** step, select one of these options for handling non-compliant packages:
* **Auto-create new repository**: The migration creates a new repository and moves non-compliant packages to the new repository.
* **Use existing repository**: The migration moves non-compliant packages to an existing repository of your choice.
9. If you chose to use an existing repository, select a repository from the list.
10. Click **Migrate**. A confirmation message appears.
**Warning**
When migration is in progress, the repository is unavailable for all developer interaction, CI pipelines, and virtual repositories. Pipelines and builds that rely on the repository will fail until the migration is complete. Migration may take some time, depending on the size and number of files in the repository.
11. Click **Migrate** again to confirm.
When migration is complete, `PackageBaseAddress` is enabled on the normalized repository. For more information, see Package Content in the Microsoft documentation.
The normalized repository uses new normalization rules and enforces the associated layout and naming standards. All packages remaining in the normalized repository are compliant with the normalization, and non-compliant packages are moved to the designated repository.
## Migrate a Remote Repository
Migrating a remote repository completes instantly. The Migration Tool makes a backup of the repository and then zaps the cache.
**To migrate a remote repository:**
1. In the **Administration** module, go to **Artifactory Settings** > **Migration Tool**. The migrations table opens.
2. Click **Create Migration**. The migration wizard opens.
3. In the **Select repository** step, select a source repository from the list.\
The list only includes repositories of the relevant package type that are not already associated with another migration.
4. Click **Save and continue to dry run**. The migration is saved and starts a dry run to check the status of packages in the repository.
**Note**
The dry run may take some time to complete. You can navigate away from the migration page and access it again later from the **Actions** menu in the migrations table.
5. Once the dry run has completed, on the **Dry run results** step, review **Total Packages**, **Normalized**, and **Failed Normalization**.
**Normalized** is the number of packages that already follow the normalization rules and will migrate successfully. **Failed Normalization** is the number of packages that do not follow those rules. A remote migration does not move those packages to an isolation repository. For the version rules, see [Understanding Normalized Versions](#understanding-normalized-versions).
6. Click **Download Report** to view a complete list of which packages will migrate successfully and which packages are non-compliant with the new normalization. Optionally, use this information to manually fix packages. To repeat the dry run, return to the **Select repository** step and click **Save and continue to dry run** again.
7. When you are satisfied with the state of the packages in the source repository, click **Set up migration**.
8. Click **Migrate**. A confirmation message appears.
9. Click **Migrate** again to confirm.
## Migrate a Smart Remote Repository
Smart remote repositories proxy repositories in another instance of Artifactory. You must migrate the origin repository before you migrate the smart remote repository. After you migrate the origin repository, you can complete the smart remote migration instantly.
**Prerequisites:** Administrator privileges used to configure the smart remote repository.
**To migrate a smart remote repository:**
1. In the **Administration** module, go to **Artifactory Settings** > **Migration Tool**. The migrations table opens.
2. Click **Create Migration**. The migration wizard opens.
3. In the **Select repository** step, select a source repository from the list.\
The list only includes repositories of the relevant package type that are not already associated with another migration.
4. Click **Save and continue to dry run**. The migration is saved and starts a dry run to check the status of packages in the repository.
5. Once the dry run has completed, on the **Dry run results** step:
* If the origin proxied by the smart remote repository hasn't been migrated, click **Save for later** to save the smart remote repository migration.
Migrate the origin repository first, then return to the saved smart remote migration from the **Actions** menu on the migrations table.
* If the origin proxied by the smart remote repository has been migrated, click **Set up migration**.
6. On the **Finalize migration** step, click **Migrate**. A confirmation message appears.
7. Click **Migrate** again to confirm.
## Migrate a Virtual Repository
**Note**
From Artifactory SaaS version 7.172.0, you can use the Migration Tool to migrate NuGet virtual repositories.
A virtual NuGet repository aggregates local, remote, and virtual repositories and doesn't store packages of its own. A virtual migration doesn't isolate or move packages. The Migration Tool checks each included repository, then marks the virtual repository as normalized when every included repository is already normalized.
You can keep a migrated, normalized repository in a non-normalized virtual repository while you finish the remaining included repositories. A normalized virtual repository can include only normalized repositories.
**To migrate a virtual repository:**
1. In the **Administration** module, go to **Artifactory Settings** > **Migration Tool**. The migrations table opens.
2. Click **Create Migration**. The migration wizard opens.
3. In the **Select repository** step, select a source virtual repository from the list.
The list only includes repositories of the relevant package type that are not already associated with another migration.
4. Click **Save and continue to dry run**. The migration is saved and starts a dry run that scans every included repository.
**Note**
The dry run reports repository counts, not package counts. You can navigate away from the migration page and access it again later from the **Actions** menu in the migrations table.
5. Once the dry run has completed, on the **Dry run results** step, review **Total Repositories**, **Normalized**, and **Failed Normalization**.
The dry run counts included repositories. **Normalized** is the number of included repositories that are already normalized. **Failed Normalization** is the number of included repositories that are not normalized. Migrate each repository counted under **Failed Normalization** before you migrate the virtual repository.
6. Click **Download Report** to view the included repositories and their normalization status.
7. On the **Dry run results** step:
* If any included repository is not normalized, use the action for that repository:
* **Create Migration**: Create a migration when one has not been started.
* **View Migration**: Open an existing migration.
* **Download Last Report**: Download the repository's latest completed dry-run or migration report.
Click **Save for later**, migrate each remaining included repository, and then return to the saved virtual migration. Use the procedure that matches the repository type.
* If every included repository is normalized, click **Set up migration**.
8. On the **Finalize migration** step, verify that the **Ready to migrate** message appears.
9. Click **Migrate**.
## Manage Migrations
You can manage migrations from the migrations table on the Migration Tool page:
* You can filter the table by status using **All Migrations**, **In Progress**, or **Migrated**. The **In Progress** filter includes dry runs that are running, dry runs that have finished, and migrations that are still running.
* Depending on each migration's status, the **Actions** menu can include:
* **Migrate**: Opens the migration setup to initiate migration.
* **Dry Run**: Immediately starts another dry run.
* **View**: Opens the migration and displays the saved configuration.
* **Download Last Report**: Downloads the latest dry run report.
* You can use additional filters and column customization to control which migrations appear in the table.
## Best Practices for NuGet Normalization
Use the following best practices when you normalize NuGet repositories with the Migration Tool.
This section also covers:
* [Understanding Normalized Versions](#understanding-normalized-versions)
* [Resolving Duplicate Versions After Migration](#resolving-duplicate-versions-after-migration)
Normalization converts NuGet package versions to a single standard form. Artifactory's NuGet V3 PackageBaseAddress API is the flat container endpoint that modern NuGet clients use to restore packages. You can only use this API on repositories with Enforce Layout enabled. Clients that only speak the older NuGet V2 protocol, such as Chocolatey and PowerShellGet, don't need Enforce Layout and can continue using non-normalized repositories.
For more information, see [NuGet Enforce Layout](/docs/nuget-repositories#nuget-enforce-layout-enabling-packagebaseaddress-api).
You can only set Enforce Layout when you create a repository. You can't toggle it on an existing repository. Use the Migration Tool to bring an existing local, remote, or virtual NuGet repository to a normalized state.
When you plan and run a migration:
* **Run a dry run first:** Review the compliant and non-compliant package report before migrating any packages.
* **Migrate included repositories first:** Migrate each included repository, then migrate the virtual repository. If any included repository isn't normalized, the virtual migration doesn't change the virtual repository and its report identifies the repositories that must be migrated first.
* **Decide the isolation target:** Before you start, choose whether non-compliant packages go to an auto-created isolation repository or an existing repository.
* **Plan for paired repositories:** Federated, replicated, and smart remote repository pairs must use the same normalization setting on both repositories. Both repositories in the pair must be normalized, or both must be non-normalized. Plan coordinated migrations for paired repositories, or remove or reconfigure the pairing until both repositories match.
* **Apply a duplicate-resolution policy:** Decide how to handle collisions before you re-upload isolated packages. For more information, see [Resolving Duplicate Versions After Migration](#resolving-duplicate-versions-after-migration).
* **Re-upload isolated packages:** After migration, re-upload isolated packages under their corrected, normalized names. Non-compliant packages move to the isolation repository unchanged. They aren't renamed.
* **Enable Enforce Layout on new repositories:** When you create new NuGet repositories, enable Enforce Layout at creation time so new packages stay normalized going forward.
* **Confirm normalization after restore:** If you archive and later restore a NuGet repository, check that the restored repository has the same normalization setting as the original. If you restore into a repository with a different setting, Artifactory may reject the packages.
**Warning**
* If every package in a repository is non-compliant, migration empties the repository, and builds or clients that depend on its content will fail. Always review the dry run report before migrating.
* You can't move, copy, or upload a non-normalized package into a normalized repository.
* A normalized smart remote repository can only point to a normalized local or remote repository.
* To configure a smart remote repository, use administrator credentials so Artifactory can confirm the target repository is normalized.
### Understanding Normalized Versions
A version is normalized when it's written as `Major.Minor.Patch`, with at least three segments, no leading zeros, no trailing `.0` fourth segment, and no build metadata suffix. NuGet treats `1`, `1.0`, `1.0.0`, and `1.0.0.0` as the same version. Normalization picks one form so a single release doesn't end up stored under multiple filenames.
The following examples show how Artifactory normalizes versions.
| Version | Result |
| :-------------- | :--------------------------------------------------- |
| `1.2.3` | Normalized, unchanged |
| `1.2.3.0` | Normalized to `1.2.3`. Trailing zero removed. |
| `1.2.3.1` | Normalized, unchanged. Non-zero fourth segment kept. |
| `1.0` | Normalized to `1.0.0` |
| `01.02.03` | Normalized to `1.2.3`. Leading zeros removed. |
| `1.2.3+build.5` | Normalized to `1.2.3`. Build metadata removed. |
**Note**
Build metadata is removed, not rejected. For example, `Package-1.0.0.0+asdfs.nupkg` is deployed as `Package-1.0.0.0.nupkg`.
Normalization rewrites valid Semantic Versioning (SemVer) versions into standard form. Artifactory rejects a package whose version doesn't follow SemVer at all. You can't upload that package to a normalized repository.
### Resolving Duplicate Versions After Migration
Two non-normalized versions can normalize to the same string. For example, `1.0.0+123` and `1.0.0+234` both become `1.0.0`, because build metadata is stripped entirely regardless of its value. The Migration Tool doesn't detect this during migration. Both packages move to the isolation repository under their original names. The duplicate appears only when you re-upload, and Artifactory rejects the second package as a conflict.
Set a resolution policy before migrating, rather than deciding case by case:
* **Prefer first-party packages:** Prefer a first-party package over a third-party or open-source package with the same coordinates.
* **Prefer the primary team owner:** If both are first-party, prefer the package owned by the repository's primary team over one in a shared or aggregate repository.
* **Prefer verified publishers:** Prefer a package from a known, verified publisher over one from an unverified source.
* **Prefer the most recent package:** If the previous rules don't pick a winner, keep the most recently published package.
* **Keep both when unresolved:** If you still can't decide, leave both packages in the isolation repository under their original names and resolve the conflict later.
## Limitations and Usage Notes
The following are limitations and usage notes for the Migration Tool in Artifactory:
* **Virtual repositories**: A virtual repository migrates only after every included repository is normalized. The Migration Tool doesn't move packages out of a virtual repository. A non-normalized virtual repository can include normalized repositories. A normalized virtual repository can include only normalized repositories.
* **Non-compliant packages**: The migration isolates packages that don't comply with the normalization rules in the repository you select. If every package in the repository is non-compliant, the migration empties the repository, and builds or clients that depend on its content fail.
* **Paired repositories**: Federation, replication, and smart remote repositories require both repositories to use the same NuGet repository type: normalized with normalized, or non-normalized with non-normalized. For more information, see [Limitations on NuGet Enforce Layout](/docs/nuget-repositories#limitations-on-nuget-enforce-layout).
**Warning**
If you migrate a paired repository so that it becomes normalized while the other repository stays non-normalized, the repositories will no longer function as intended. Plan coordinated migrations for paired repositories, or remove or reconfigure federation and replication until both repositories match.
## Frequently Asked Questions
This section provides answers to frequently asked questions.
##### Q: How do I migrate a NuGet repository with the Migration Tool?
**A:** Create a migration in **Artifactory Settings** > **Migration Tool**, run the dry run, review the report, set an isolation repository for non-compliant packages, then migrate. For step-by-step instructions, see [Migrate a Local Repository](#migrate-a-local-repository).
##### Q: Can I turn on Enforce Layout for an existing NuGet repository?
**A:** No. You can only set Enforce Layout when you create a repository. To normalize an existing local, remote, smart remote, or virtual NuGet repository, use the Migration Tool. For more information, see [Best Practices for NuGet Normalization](#best-practices-for-nuget-normalization).
##### Q: How do I migrate a virtual NuGet repository?
**A:** Migrate every included repository first. Then create a migration for the virtual repository, run the dry run, and migrate when the report shows that all included repositories are normalized. For step-by-step instructions, see [Migrate a Virtual Repository](#migrate-a-virtual-repository).
##### Q: What happens to non-compliant packages during migration?
**A:** Non-compliant packages move to the isolation repository you select and keep their original names. They aren't renamed during migration. After migration, re-upload them under corrected, normalized names.
##### Q: What permissions do I need to use the Migration Tool?
**A:** You need Admin or Project Admin permissions. Smart remote migration also requires administrator privileges used to configure the smart remote repository.
##### Q: Why must federated, replicated, and smart remote pairs use the same normalization setting?
**A:** Both repositories in the pair must be normalized, or both must be non-normalized. If only one side is normalized, the pairing won't work as intended. For more information, see [Limitations and Usage Notes](#limitations-and-usage-notes).
## Related Topics
* [NuGet Enforce Layout](/docs/nuget-repositories#nuget-enforce-layout-enabling-packagebaseaddress-api)
* [Limitations on NuGet Enforce Layout](/docs/nuget-repositories#limitations-on-nuget-enforce-layout)
* [Local Repositories](/docs/local-repositories)
* [Remote Repositories](/docs/remote-repositories)
* [Virtual Repositories](/docs/virtual-repositories)