Restore packages with NuGet Package Restore
NuGet Package Restore restores all of a project's dependencies that are listed in either a project file or a packages.config file. You can restore packages manually with
msbuild -t:restore, or through Visual Studio. The
dotnet build and
dotnet run commands automatically restore packages, and you can configure Visual Studio to restore packages automatically when it builds a project.
To promote a cleaner development environment and to reduce repository size, Package Restore makes all of a project's dependencies available without having to store them in source control. To configure your source control repository to exclude package binaries, see Packages and source control.
Package Restore behavior
Package Restore tries to install all package dependencies to the state that matches the
<PackageReference>s in a project file, such as .csproj, or
<package>s in a packages.config file. Package Restore first installs the direct dependencies of a project as needed, then installs any dependencies of those packages throughout the entire dependency graph.
If a needed package isn't already installed, NuGet first attempts to retrieve it from the local global packages or HTTP cache folders. If the package isn't in the local folders, NuGet tries to download it from all sources configured in Visual Studio at Tools > Options > NuGet Package Manager > Package Sources.
During restore, NuGet ignores the order of package sources, and uses the package from the first source that responds to requests. If restore fails, NuGet doesn't indicate the failure until after it checks all sources. NuGet then reports a failure for only the last source in the list. The error implies that the package wasn't present on any of the sources, even though it doesn't list the other failures individually.
For more information about NuGet behavior, see Common NuGet configurations.
If the package references in your project file or packages.config file are correct, use your preferred tool to restore packages:
After a successful restore:
- For projects that use
<PackageReference>, the package is present in the local global-packages folder, and the project obj/project.assets.json file is recreated.
- For projects that use packages.config, the package appears in the project's packages folder.
- The project should now build successfully.
If the package references in your project file or your packages.config file are incorrect and don't match your desired state, install or update the correct packages instead of using Package Restore.
If you have missing packages or package-related errors after you run Package Restore, such as error icons in Solution Explorer, follow the instructions in Troubleshooting Package Restore errors, or reinstall or update the packages. In Visual Studio, the Package Manager Console provides several options for reinstalling packages. For more information, see Use Package-Update.
Restore packages in Visual Studio
In Visual Studio on Windows, you can restore packages automatically or manually. First, configure Package Restore through Tools > Options > NuGet Package Manager.
Configure Visual Studio Package Restore options
Configure the following Package Restore options at Tools > Options > NuGet Package Manager > General.
Allow NuGet to download missing packages
Select Allow NuGet to download missing packages to enable package restore and the Restore NuGet Packages command. This selection sets the
packageRestore/enabled setting to
True in the packageRestore section of the global NuGet.Config file, at %AppData%\Roaming\NuGet on Windows or ~/.nuget/NuGet/ on Mac or Linux.
<configuration> <packageRestore> <add key="enabled" value="True" /> </packageRestore> </configuration>
To globally override the
packageRestore/enabled setting, you can set the environment variable EnableNuGetPackageRestore to True or False before you open Visual Studio or start a build.
To enable or disable Package Restore for all users on a computer, you can add the configuration settings to the global NuGet.Config file in Windows at %ProgramData%\NuGet\Config, sometimes under a specific <IDE>\<Version>\<SKU> Visual Studio folder, or in Mac/Linux at ~/.local/share. Individual users can then selectively enable restore as needed on a project level. For more details on how NuGet prioritizes multiple config files, see Common NuGet configurations.
If you edit the
packageRestore settings in NuGet.Config directly, restart Visual Studio so that the Options show the current values.
Automatically check for missing packages during build
Select Automatically check for missing packages during build in Visual Studio to automatically restore any missing packages when you run a build from Visual Studio. This setting doesn't affect builds run from the MSBuild command line. This selection sets the
packageRestore/automatic setting to
True in the
packageRestore section of the NuGet.Config file.
<configuration> <packageRestore> <add key="automatic" value="True" /> </packageRestore> </configuration>
For non-SDK-style projects, you must select Allow NuGet to download missing packages as well as Automatically check for missing packages during build in Visual Studio in Options to enable automatic restore.
Choose the default package management format
NuGet has two package management formats, PackageReference and packages.config. Select the format you want to use from the dropdown list under Package Management. You can also select whether to allow format selection on first package install.
If a project doesn't support both package management formats, NuGet uses the package management format that's compatible with the project, which might not be the default you set in the options. NuGet then won't prompt for selection on first install, even if you selected that option.
If you use Package Manager Console to install the first package in a project, NuGet doesn't prompt for format selection, even if that option is selected in Options.
Restore packages manually or automatically
After you enable package restore in Options, you can right-click the solution in Solution Explorer and select Restore NuGet Packages to restore packages anytime.
If you enabled automatic restore in Options, Package Restore happens automatically when you create a project from a template or build a project. For NuGet 4.0+, restore also happens automatically when you make changes to a SDK-style project.
For projects that use
<PackageReference>, you can see the package references in Visual Studio Solution Explorer under Dependencies > Packages. Packages that don't install properly when you manually restore or run a build display error icons in Solution Explorer. Right-click the project, select Manage NuGet Packages, and use the NuGet Package Manager to uninstall and reinstall the affected packages. For more information, see Reinstall and update packages.
If you see the error This project references NuGet package(s) that are missing on this computer, or One or more NuGet packages need to be restored but couldn't be because consent has not been granted, make sure you enabled automatic restore. For older projects, see Migrate to automatic package restore. Also see Troubleshooting package restore errors.
Restore by using the dotnet CLI
.NET Core 2.0 and later
dotnet build and
dotnet run commands restore packages automatically. As of NuGet 4.0,
dotnet restore runs the same code as
To restore a package with
- Open a command line and switch to the directory that contains your project file.
To add a missing package reference to the project file, use dotnet add package, which also runs
Restore by using the NuGet CLI
restore command only adds packages to disk, but doesn't modify the project file or packages.config. To add project dependencies, use the Visual Studio Package Manager UI or Console.
To restore packages, run the following command:
nuget restore <projectPath>
restore command uses a solution file or a package.config file in the specified project path.
For example, to restore all packages for MySolution.sln in the current directory, run:
nuget restore MySolution.sln
For non-SDK-style projects that use
PackageReference, use msbuild -t:restore to restore packages instead.
Restore by using MSBuild
You can use msbuild -t:restore to restore packages in NuGet 4.x+ and MSBuild 15.1+, which are included with Visual Studio 2017 and higher.
This command restores packages in projects that use PackageReference for package references. Starting with MSBuild 16.5+, the command also supports packages.config package references, when used with
To use MSBuild restore:
Open a Developer Command Prompt by searching for developer command prompt and starting the prompt from the Windows Start menu, which configures all the necessary paths for MSBuild.
Switch to the project folder, and enter
After the restore completes, enter
msbuildto rebuild the project. Make sure the MSBuild output indicates that the build completed successfully.
You can use
msbuild -restore to run
restore, reload the project, and build, since build is the default target. For more information, see Restore and build with one MSBuild command.
Restore with Azure Pipelines or Azure DevOps Server
When you create a build definition in Azure Pipelines, you can include the NuGet CLI restore or dotnet CLI restore task in the definition before any build tasks. Some build templates include the restore task by default.
Azure DevOps Server and TFS 2013 and later automatically restore packages during build, if you use a TFS 2013 or later Team Build template. You can also include a build step to run a command-line restore option, or optionally migrate the build template to a later version. For more information, see Set up package restore with Team Foundation Build.
Constrain package versions
NuGet restore through any method honors any version constraints you specify in packages.config or the project file.
In packages.config, you can specify an
allowedVersionsrange in the dependency. For more information, see Constraints on upgrade versions. For example:
<package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />
In a project file, you can specify the version range in the
Versionproperty of the dependency. For example:
<PackageReference Include="Newtonsoft.json" Version="[6,7)" />
In both cases, use the notation described in Package versioning.
Force restore from remote package sources
By default, NuGet restore operations use packages from the local global-packages and http-cache folders, as described in Manage the global packages and cache folders. To avoid using these local packages, use the following options.
To clear all local caches:
- In Visual Studio, select the Clear All NuGet Cache(s) button at Tools > Options > NuGet Package Manager > General.
- In the dotnet CLI, use
dotnet nuget locals all --clear.
- In the NuGet CLI, use
nuget locals all -clear.
To avoid using the packages in the global-packages folder:
- Clear the folder by using
nuget locals global-packages -clearor
dotnet nuget locals global-packages --clear.
- Temporarily set the NUGET_PACKAGES environment variable to a different folder.
- Create a NuGet.Config file that sets
repositoryPathfor packages.config, to a different folder. For more information, see configuration settings.
- For MSBuild only, specify a different folder with the
To avoid using packages in the HTTP cache:
- Clear the cache by using
nuget locals http-cache -clearor
dotnet nuget locals http-cache --clear.
- Temporarily set the NUGET_HTTP_CACHE_PATH environment variable to a different folder.
nuget restore, use the
-NoHttpCacheoption, or for
dotnet restore, use the
--no-http-cacheoption. These options don't affect restore operations through the Visual Studio Package Manager or Console.
Migrate to automatic package restore
Earlier versions of NuGet supported an MSBuild-integrated package restore. Projects that use the deprecated MSBuild-integrated package restore should migrate to automatic package restore.
These projects typically contain a .nuget folder with three files: NuGet.config, nuget.exe, and NuGet.targets. The NuGet.targets file causes NuGet to use the MSBuild-integrated approach, so it must be removed.
To migrate to automatic package restore:
- Enable automatic package restore.
- Close Visual Studio.
- Delete .nuget/nuget.exe and .nuget/NuGet.targets.
- For each project file, remove the
<RestorePackages>element, and remove any references to NuGet.targets.
To test automatic package restore:
- Remove the packages folder from the solution.
- Open the solution in Visual Studio and start a build. Automatic package restore should download and install each dependency package, without adding it to source control.