dotnet restore: Restore NuGet Dependencies
dotnet restore resolves and downloads the NuGet packages declared in a project or solution into the global packages folder.
Restore is the first real step of a .NET build. In CI it is also where most failures surface, because it is the step that talks to package feeds.
What it does
dotnet restore reads the PackageReference items in your project (or every project in a solution), resolves a compatible version graph, and downloads the packages into the global packages folder (~/.nuget/packages by default). dotnet build and dotnet test run an implicit restore first unless you pass --no-restore.
Common usage
dotnet restore
dotnet restore MySolution.sln
dotnet restore --locked-mode # fail if packages.lock.json is out of date
dotnet restore --packages ./.nuget-packages # restore into a project-local folderOptions
| Flag | What it does |
|---|---|
| --packages <dir> | Restore packages into this directory instead of the global folder |
| --locked-mode | Fail if packages.lock.json does not match the project (requires RestorePackagesWithLockFile) |
| --use-lock-file | Generate or use packages.lock.json |
| -s, --source <url> | Override the package sources to restore from |
| --configfile <file> | Use a specific NuGet.config |
| --no-cache | Do not use the HTTP cache for the restore |
| -v, --verbosity <level> | q[uiet], m[inimal], n[ormal], d[etailed], diag[nostic] |
In CI
Cache ~/.nuget/packages keyed on the hash of your lock files (packages.lock.json or *.csproj) so restore is a no-op on cache hits. Commit packages.lock.json and run dotnet restore --locked-mode so an unexpected dependency change fails the build instead of pulling a new version silently. Restore once at the top of the job, then pass --no-restore to every later build/test/publish so they do not redo the work.
Common errors in CI
NU1101 ("Unable to find package X") means the package or version is not on any configured source, often a missing private feed or a wrong NuGet.config. NU1301 ("Unable to load the service index for source") is a feed that is unreachable or returned a non-200, frequently a flaky network or an expired token. NU1403 ("content hash validation failed") means a corrupted cached package; clear ~/.nuget/packages or run dotnet nuget locals all --clear.