Moving a project from packages.config to PackageReference means replacing the list of packages in packages.config with <PackageReference> items in the project file, then removing everything the old format added to that file: assembly references into the packages folder, imported build files and the restore check target. This guide is for the developer doing the job on an older .NET Framework solution, and for the IT manager who wants to know why it is the first step of almost any move to modern .NET.
Modern .NET only understands PackageReference, so a project still on packages.config has to be converted before it can move to .NET 10, the current long-term support release, supported until 14 November 2028. It is also worth doing on its own: restores are faster, the packages folder disappears from the solution, and the project file says which packages the code actually depends on.
Why it is not just a find and replace
With packages.config, NuGet did its work by editing the project file. Installing a package added a <Reference> with a HintPath into the packages folder for every assembly, an <Import> for any .props or .targets file the package shipped, and an EnsureNuGetPackageBuildImports target that fails the build if the packages folder is missing. Some packages also ran an install.ps1 script, copied files into the project from their content folder, or applied XDT transforms to web.config.
PackageReference does all of that at build time instead. So the conversion is two jobs: write the new items, and take out every trace of the old ones. Miss the second and the project builds against two copies of the same assembly.
What goes wrong when it is done by hand
- Old references left behind. A
<Reference>with aHintPathinto the packages folder still resolves on the machine that has the folder, so the project looks fine there and breaks on a clean build server. - Duplicate imports. A package’s
.targetsimported by hand and again by NuGet gives warnings at best and double build steps at worst. - Transitive packages promoted to direct ones. packages.config lists every package, including those only there because another package needs them. Converting the list one for one works, but pins versions nobody chose on purpose.
- Package scripts and content stop running. Microsoft’s migration guide is clear that
install.ps1scripts are not run,contentfolder assets are not copied, and XDT transforms are not applied under PackageReference. Anything the project relied on them for has to be done in the project itself. - Version constraints disappear. An
allowedVersionsattribute in packages.config has no PackageReference equivalent, so the limit someone once set on purpose is lost unless it is written down. - Analysers flow to other projects. A package marked
developmentDependency="true"needsPrivateAssets="all"on its new item, or it is passed on to every project that references this one.
Doing it by hand: the steps
- Check the tooling. PackageReference needs Visual Studio 2017 or later. Visual Studio has a built-in migrator (right-click packages.config or References, then “Migrate packages.config to PackageReference”), available from version 15.7. Microsoft’s documentation says it is not available for ASP.NET or C++ projects, which rules it out for many of the older web applications that most need the move.
- Back up and branch. Do one project at a time, starting with libraries that nothing else depends on, so that a failed build has one cause.
- Write the items. For each
<package>in packages.config, add<PackageReference Include="Id" Version="x.y.z" />to an<ItemGroup>in the project file. Development dependencies getPrivateAssets="all". Drop thetargetFrameworkattributes: PackageReference restores for the project’s current framework. - Tell NuGet. In an old-style project file (no
Sdkattribute), add<RestoreProjectStyle>PackageReference</RestoreProjectStyle>to the firstPropertyGroup. - Remove the old wiring. Every
<Reference>whoseHintPathpoints into the packages folder, every<Import>of a package.propsor.targetsfile, theEnsureNuGetPackageBuildImportstarget, and the<None Include="packages.config" />item. - Delete packages.config and the packages folder, restore and build. Packages now come from the user-level cache.
- Prune. Remove the packages you never reference directly. They come back through the packages that need them.
- Replace what the scripts did. For each package that had an install script, content files or a transform, check what it added and make sure the project now carries it itself.
The checks before you call it done
- A clean clone builds on a machine that has never had the packages folder, ideally the build server.
- No
HintPathin any project file still points atpackages\. - The build output contains the same assemblies, at the same versions, as before. Comparing the bin folders is quick and catches most surprises.
- Config transforms and copied content files still appear in the published output.
- Any version limits that
allowedVersionsused to enforce are recorded somewhere the next person will see them.
The shortcut
We built the free packages.config to PackageReference converter to do steps 3 to 5 without Visual Studio. Paste packages.config, and ideally the project file beside it, and it gives you the ItemGroup to paste in, with development dependencies already marked, plus a list of the references, imports and targets to remove from that particular project file. It shows every change rather than making it, and it works on the ASP.NET projects the Visual Studio migrator refuses. It runs in your browser and nothing is sent anywhere.
It does not replace steps 7 and 8: it cannot tell which packages your code uses directly, or what an install script once did. Before converting, the NuGet upgrade planner checks each package for vulnerabilities, deprecation and a release that supports modern .NET, which tells you which packages will survive the wider move at all. If the project is going all the way to ASP.NET Core, our guide to moving web.config to appsettings.json covers the configuration side.
The converter is free, with no account or sign-up: packages.config to PackageReference converter.