In this article

Different ways to install a NuGet Package

02/12/2018

4 minutes to read

Contributors

In this article

NuGet packages are downloaded and installed using any of the methods in the following table (see Install NuGet client tools if you don't have these installed already). The package may be retrieved from a cache instead of downloaded.

Method

Description

dotnet.exe CLIdotnet add package <package_name>

(All platforms) Retrieves the package identified by <package_name>, expands its contents into a folder in the current directory, and adds a reference to the project file. Also retrieves and installs dependencies.

(Windows and Mac) Provides a UI through which you can browse, select, and install packages and their dependencies into a project from a specified package source. Adds references to installed packages to the project file.

(Windows only) Retrieves and installs the package identified by <package_name> from a selected source into a specified project in the solution, then adds a reference to the project file. Also retrieves and installs dependencies.

(All platforms) Retrieves the package identified by <package_name> and expands its contents into a folder in the current directory; can also retrieve all packages listed in a packages.config file. Also retrieves and installs dependencies, but makes no changes to project files or packages.config.

What happens when a package is installed

Simply said, the different NuGet tools typically create a reference to a package in the project file or packages.config, then perform a package restore, which effectively installs the package. The exception is nuget install, which only expands the package into a packages folder and does not modify any other files.

The general process is as follows:

(All tools except nuget.exe) Record the package identifer and version into the project file or packages.config.

If the package is not in the global-packages folder, attempt to retrieve it from the sources listed listed in the configuration files. For online sources, attempt first to retrieve the package from the cache unless -NoCache is specified with nuget.exe commands or --no-cache is specified with dotnet restore. (Visual Studio and dotnet add package always use the cache.) If a package is used from the cache, "CACHE" appears in the output. The cache has an expiration time of 30 minutes.

If the package is not in the cache, attempt to download it from the sources listed in the configuration. If a package is downloaded, "GET" and "OK" appear in the output.

If the package cannot be successfully acquired from any sources, installation fails at this point with an error such as NU1103. Note that errors from nuget.exe commands show only the last source checked, but implies that the package wasn't available from any source.

When acquiring the package, the order of sources in the NuGet configuration may apply:

For projects using the PackageReference format, NuGet checks sources local folder and network shares before checking HTTP sources.

For projects using the packages.config management format, NuGet uses the order of the sources in the configuration. An exception is restore operations, in which case source ordering is ignored and NuGet uses the package from whichever source responds first.

In general, the order in which NuGet checks sources isn't particularly meaningful, because any given package with a specific identifier and version number is exactly the same on whatever source it's found.

If downloaded, install the package into the per-user global-packages folder. NuGet creates a subfolder for each package identifier, then creates subfolders for each installed version of the package.

Update other project files and folders:

For projects using PackageReference, update the package dependency graph stored in obj/project.assets.json. Package contents themselves are not copied into any project folder.

For projects using packages.config, copy those parts of the expanded package that match the project's target framework into project's packages folder. (When using nuget install, the entire expanded package is copied because nuget.exe does not examine project files to identify the target framework.)