Ubuntu Manpage: This article applies to: ✔️ .NET Core 3.1 SDK and later versions

Provided by: dotnet-host-9.0_9.0.7-0ubuntu1~25.04.1_amd64

dotnet restore

       This article applies to: ✔️ .NET Core 3.1 SDK and later versions

NAME

       dotnet-restore - Restores the dependencies and tools of a project.

SYNOPSIS

              dotnet restore [<ROOT>] [--configfile <FILE>] [--disable-build-servers]
                  [--disable-parallel]
                  [-f|--force] [--force-evaluate] [--ignore-failed-sources]
                  [--interactive] [--lock-file-path <LOCK_FILE_PATH>] [--locked-mode]
                  [--no-cache] [--no-dependencies] [--packages <PACKAGES_DIRECTORY>]
                  [-r|--runtime <RUNTIME_IDENTIFIER>] [-s|--source <SOURCE>]
                  [--tl:[auto|on|off]] [--use-current-runtime, --ucr [true|false]]
                  [--use-lock-file] [-v|--verbosity <LEVEL>]

              dotnet restore -h|--help

DESCRIPTION

A .NET project typically references external libraries in NuGet (https://www.nuget.org) packages that
provide additional functionality. These external dependencies are referenced in the project file
(.csproj or .vbproj). When you run the dotnet restore command, the .NET CLI uses NuGet to look for these
dependencies and download them if necessary. It also ensures that all the dependencies required by the
project are compatible with each other and that there are no conflicts between them. Once the command is
completed, all the dependencies required by the project are available in a local cache and can be used by
the .NET CLI to build and run the application.

In most cases, you don’t need to explicitly use the dotnet restore command, since if a NuGet restore is
necessary, the following commands run it implicitly:

• dotnet new

• dotnet build

• dotnet build-server

• dotnet run

• dotnet test

• dotnet publish

• dotnet pack

Sometimes, it might be inconvenient to run the implicit NuGet restore with these commands. For example,
some automated systems, such as build systems, need to call dotnet restore explicitly to control when the
restore occurs so that they can control network usage. To prevent the implicit NuGet restore, you can
use the --no-restore flag with any of these commands.

Signed package verification during restore operations requires a certificate root store that is
valid for both code signing and timestamping. For more inforomation, see NuGet signed package
verification.

Specify feeds
To restore the dependencies, NuGet needs the feeds where the packages are located. Feeds are usually
provided via the nuget.config configuration file. A default configuration file is provided when the .NET
SDK is installed. To specify additional feeds, do one of the following:

• Create your own nuget.config file in the project directory. For more information, see Common NuGet
configurations and nuget.config differences later in this article.

• Use dotnet nuget commands such as dotnet nuget add source.

You can override the nuget.config feeds with the -s option.

For information about how to use authenticated feeds, see Consuming packages from authenticated feeds.

Global packages folder
For dependencies, you can specify where the restored packages are placed during the restore operation us‐
ing the --packages argument. If not specified, the default NuGet package cache is used, which is found
in the .nuget/packages directory in the user’s home directory on all operating systems. For example,
/home/user1 on Linux or C: on Windows.

Project-specific tooling
For project-specific tooling, dotnet restore first restores the package in which the tool is packed, and
then proceeds to restore the tool’s dependencies as specified in its project file.

nuget.config differences
The behavior of the dotnet restore command is affected by the settings in the nuget.config file, if
present. For example, setting the globalPackagesFolder in nuget.config places the restored NuGet pack‐
ages in the specified folder. This is an alternative to specifying the --packages option on the dotnet
restore command. For more information, see the nuget.config reference.

There are three specific settings that dotnet restore ignores:

• bindingRedirects

Binding redirects don’t work with <PackageReference> elements and .NET only supports <PackageReference>
elements for NuGet packages.

• solution

This setting is Visual Studio specific and doesn’t apply to .NET. .NET doesn’t use a packages.config
file and instead uses <PackageReference> elements for NuGet packages.

• trustedSigners

Support for cross-platform package signature verification was added in the .NET 5.0.100 SDK.

Workload manifest downloads
When you run this command, it initiates an asynchronous background download of advertising manifests for
workloads. If the download is still running when this command finishes, the download is stopped. For
more information, see Advertising manifests.

ARGUMENTS

       • ROOT

         Optional path to the project file to restore.

OPTIONS

• -a|--arch <ARCHITECTURE>

Specifies the target architecture. This is a shorthand syntax for setting the Runtime Identifier
(RID), where the provided value is combined with the default RID. For example, on a win-x64 machine,
specifying --arch x86 sets the RID to win-x86. If you use this option, don’t use the -r|--runtime op‐
tion. Available since .NET 6 Preview 7.

• --configfile <FILE>

The NuGet configuration file (nuget.config) to use. If specified, only the settings from this file
will be used. If not specified, the hierarchy of configuration files from the current directory will
be used. For more information, see Common NuGet Configurations.

• --disable-build-servers

Forces the command to ignore any persistent build servers. This option provides a consistent way to
disable all use of build caching, which forces a build from scratch. A build that doesn’t rely on
caches is useful when the caches might be corrupted or incorrect for some reason. Available since .NET
7 SDK.

• --disable-parallel

Disables restoring multiple projects in parallel.

• --force

Forces all dependencies to be resolved even if the last restore was successful. Specifying this flag
is the same as deleting the project.assets.json file.

• --force-evaluate

Forces restore to reevaluate all dependencies even if a lock file already exists.

• -?|-h|--help

Prints out a description of how to use the command.

• --ignore-failed-sources

Only warn about failed sources if there are packages meeting the version requirement.

• --interactive

Allows the command to stop and wait for user input or action. For example, to complete authentication.

• --lock-file-path <LOCK_FILE_PATH>

Output location where project lock file is written. By default, this is PROJECT_ROOT.lock.json.

• --locked-mode

Don’t allow updating project lock file.

• --no-cache

Specifies to not cache HTTP requests.

• --no-dependencies

When restoring a project with project-to-project (P2P) references, restores the root project and not
the references.

• --packages <PACKAGES_DIRECTORY>

Specifies the directory for restored packages.

• -r|--runtime <RUNTIME_IDENTIFIER>

Specifies a runtime for the package restore. This is used to restore packages for runtimes not explic‐
itly listed in the <RuntimeIdentifiers> tag in the .csproj file. For a list of Runtime Identifiers
(RIDs), see the RID catalog.

• -s|--source <SOURCE>

Specifies the URI of the NuGet package source to use during the restore operation. This setting over‐
rides all of the sources specified in the nuget.config files. Multiple sources can be provided by
specifying this option multiple times.

• --tl:[auto|on|off]

Specifies whether the terminal logger should be used for the build output. The default is auto, which
first verifies the environment before enabling terminal logging. The environment check verifies that
the terminal is capable of using modern output features and isn’t using a redirected standard output
before enabling the new logger. on skips the environment check and enables terminal logging. off
skips the environment check and uses the default console logger.

The terminal logger shows you the restore phase followed by the build phase. During each phase, the
currently building projects appear at the bottom of the terminal. Each project that’s building outputs
both the MSBuild target currently being built and the amount of time spent on that target. You can
search this information to learn more about the build. When a project is finished building, a single
“build completed” section is written that captures:

• The name of the built project.

• The target framework (if multi-targeted).

• The status of that build.

• The primary output of that build (which is hyperlinked).

• Any diagnostics generated for that project.

This option is available starting in .NET 8.

• --use-current-runtime, --ucr [true|false]

Sets the RuntimeIdentifier to a platform portable RuntimeIdentifier based on the one of your machine.
This happens implicitly with properties that require a RuntimeIdentifier, such as SelfContained, Pub‐
lishAot, PublishSelfContained, PublishSingleFile, and PublishReadyToRun. If the property is set to
false, that implicit resolution will no longer occur.

• --use-lock-file

Enables project lock file to be generated and used with restore.

• -v|--verbosity <LEVEL>

Sets the verbosity level of the command. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed],
and diag[nostic]. The default is minimal. For more information, see <xref:Microsoft.Build.Frame‐
work.LoggerVerbosity>.

EXAMPLES

       • Restore dependencies and tools for the project in the current directory:

                dotnet restore

       • Restore dependencies and tools for the app1 project found in the given path:

                dotnet restore ./projects/app1/app1.csproj

       • Restore the dependencies and tools for the project in the current directory using the file path provid‐
         ed as the source:

                dotnet restore -s c:\packages\mypackages

       • Restore the dependencies and tools for the project in the current directory using the  two  file  paths
         provided as sources:

                dotnet restore -s c:\packages\mypackages -s c:\packages\myotherpackages

       • Restore dependencies and tools for the project in the current directory showing detailed output:

                dotnet restore --verbosity detailed

   Audit for security vulnerabilities
       Starting  in .NET 8, dotnet restore includes NuGet security auditing.  This auditing produces a report of
       security vulnerabilities with the affected package name, the severity of the vulnerability, and a link to
       the advisory for more details.

       To opt out of the security auditing, set the <NuGetAudit> MSBuild property to false in your project file.

       To retrieve the known vulnerability dataset, ensure that you have the NuGet.org central registry  defined
       as one of your package sources:

              <packageSources>
                  <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
              </packageSources>

       You  can configure the level at which auditing will fail by setting the <NuGetAuditLevel> MSBuild proper‐
       ty.  Possible values are low, moderate, high, and critical.  For example if you only want to  see  moder‐
       ate, high, and critical advisories, you can set the property to moderate.

       Starting  in  .NET 9, NuGet audits both direct and transitive package references, by default.  In .NET 8,
       only direct package references are audited.  You can change the mode by setting the <NuGetAuditMode>  MS‐
       Build property to direct or all.

       For more information, see Auditing package dependencies for security vulnerabilities.

                                                   2024-10-02                                  dotnet-restore(1)