skip to content

Restore, Lock & Audit

What dotnet restore does: the global packages folder, packages.lock.json in locked mode, nuget.config sources with source mapping, and NuGetAudit warnings. Asked because restore breaks CI first.

on this pageshow

explore

questions

5

With the .NET 10 SDK, what does dotnet restore produce, where do the restored packages land, and when would you run dotnet nuget locals?

level: juniorimportance: must knowfreq 60%

answer

  1. build, test, run and publish restore implicitly
  2. obj/project.assets.json is the resolved graph
  3. ~/.nuget/packages, overridden by NUGET_PACKAGES
  4. http-cache, global-packages, temp, plugins-cache
  5. dotnet nuget locals all --list

basics

~20 s

dotnet restore resolves the project's package graph, extracts each package once into the global packages folder (~/.nuget/packages by default) and writes obj/project.assets.json for the build. dotnet nuget locals lists or clears that folder and NuGet's other caches.

solid answer

~40 s

`dotnet restore` reads the project's `PackageReference` and `ProjectReference` items, resolves the full graph against the sources in `nuget.config`, and extracts every package into the **global packages folder** — `%userprofile%\.nuget\packages` on Windows, `~/.nuget/packages` elsewhere, overridable with `NUGET_PACKAGES`, `globalPackagesFolder` or `RestorePackagesPath`. Projects use packages straight from there; nothing is copied into the repo. Restore writes `obj/project.assets.json` (the resolved graph the build reads), `project.nuget.cache` for no-op checks, and the generated `.nuget.g.props` / `.nuget.g.targets`. `dotnet build`, `test`, `run`, `publish` and `pack` restore implicitly unless given `--no-restore`. `dotnet nuget locals <all|http-cache|global-packages|temp|plugins-cache> --list` shows the cache paths and `--clear` empties them — useful when a cached package or HTTP response is corrupt, not as a routine fix.

code

bash · 5 lines
bash
dotnet restore Payments.sln
dotnet build Payments.sln --no-restore -c Release

dotnet nuget locals all --list           # print every cache path
dotnet nuget locals http-cache --clear    # drop cached feed responses

go deeper

for a junior

Recall that restore downloads packages into ~/.nuget/packages, that build and test restore for you, and that dotnet nuget locals clears the caches.

for a middle

Explain what lands in obj, how the no-op check works, the lookup order across the global packages folder, http-cache and feeds, and how to relocate the folder.

for a senior

Shape CI restores: one explicit restore with the repo's config, --no-restore afterwards, job-local package folders, and clearing caches only when a corrupt or replaced package is the real cause.

for a principal

Balance shared package caches for speed against isolation and auditability across many build agents, and decide where package folders live in a regulated pipeline.

## What restore is for A .NET project file only **names** its dependencies. Before the compiler can run, NuGet must turn those names into files on disk: work out the full graph, download what is missing and tell MSBuild where everything is. That step is **restore**. You can run it explicitly with `dotnet restore`, but `dotnet build`, `dotnet test`, `dotnet run`, `dotnet publish` and `dotnet pack` run it implicitly first, which is why a fresh clone builds with one command. ## What it produces In the project's `obj` folder (the `MSBuildProjectExtensionsPath`), restore writes: | File | Purpose | |---|---| | `project.assets.json` | the resolved dependency graph and the asset paths for every target framework; the build reads it | | `project.nuget.cache` | a fingerprint of restore's inputs, so an unchanged project gets a fast **no-op restore** | | `<project>.csproj.nuget.g.props` / `.nuget.g.targets` | imports of build logic shipped inside packages | None of these belong in source control; they are regenerated on every machine. ## Where the packages go With PackageReference, packages are **not** copied into the repository. Each one is extracted once into the **global packages folder**, in a subfolder per id and version, and every project on the machine uses it from there: - Windows: `%userprofile%\.nuget\packages`; macOS and Linux: `~/.nuget/packages`. - Override it with the `NUGET_PACKAGES` environment variable (highest precedence), the `globalPackagesFolder` setting in `nuget.config`, or the `RestorePackagesPath` property — which is what `dotnet restore --packages <dir>` sets. When asked for a package, NuGet looks in the global packages folder first, then in non-HTTP sources, then in the **http-cache**, and only then over the network. The folder is never pruned automatically; it grows until someone cleans it. ## The four local caches `dotnet nuget locals` manages them by name: - **global-packages** — the extracted packages described above. - **http-cache** — cached responses and downloads from HTTP feeds (`%localappdata%\NuGet\v3-cache` or `~/.local/share/NuGet/v3-cache`). - **temp** — scratch space used while extracting. - **plugins-cache** — results NuGet caches from its plugins, such as credential providers. - **all** — every one of the above. The command requires exactly one of `--list` (`-l`), which prints paths, or `--clear` (`-c`), which deletes contents. ## When clearing actually helps 1. A package was pushed, deleted and re-pushed with the same version on a private feed, and the old bytes are cached — clear `http-cache` and `global-packages`. 2. Extraction was interrupted and a package folder is half-written; restore normally detects that through the package's `.nupkg.metadata` file, but clearing the folder settles it. 3. A build agent's disk is full of old versions — clear `global-packages`, accepting that the next restore downloads everything again. What clearing does **not** do is change which versions resolve. Resolution is deterministic from the project files and the feeds; an empty cache just means the same versions are downloaded again. ## Reading a failed restore Most restore failures name their cause in the code: | Code | Meaning | First check | |---|---|---| | NU1101 | no package with that id on the sources | the id's spelling and the configured feeds | | NU1102 | the id exists but no version satisfies the range | the version range, or a feed that lacks the release | | NU1301 | a source could not be loaded | the URL, the network and the feed's credentials | | NU1100 | a dependency could not be resolved at all | `dotnet nuget list source` — there may be no sources configured | NU1101 and NU1102 list the sources they searched and the nearest versions they found, which usually settles whether the package is missing or merely not visible from this machine. `--ignore-failed-sources` lets restore continue past an unreachable source, which can hide exactly the problem you are looking for, so it is not a CI default. ## Restore switches worth knowing - `--no-restore` on build, test or publish — skip the implicit restore after an explicit one, standard in CI. - `--force` — re-resolve even if the no-op check says nothing changed. - `--no-http-cache` — ignore cached HTTP responses for this run. - `--source` — use these feeds instead of the configured ones. - `--configfile` — use only this `nuget.config`. In a bank's build, the usual shape is one explicit `dotnet restore` step with the repository's own `nuget.config`, then `dotnet build --no-restore` and `dotnet test --no-build`, so restore problems surface in one place with clear logs.

  • Why does a second dotnet build finish restore almost instantly?
    Restore writes `project.nuget.cache` with a fingerprint of its inputs — package references, sources, target frameworks. If nothing changed and the expected packages are still in the global packages folder, restore reports a no-op without contacting the feeds. `--force` bypasses that check.
  • How would you give each CI job its own package folder?
    Set `NUGET_PACKAGES` to a job-local directory, or pass `dotnet restore --packages <dir>`, which sets `RestorePackagesPath`. The environment variable beats the `globalPackagesFolder` setting in `nuget.config`. A per-repo folder also matters when package source mapping is in use, because packages already in a shared folder skip the source lookup.

  • Restore copies every package into a packages folder inside the repository.
  • obj/project.assets.json should be committed so builds are repeatable.
  • dotnet clean empties the NuGet global packages folder.
  • Clearing the NuGet caches makes restore pick newer package versions.
  • dotnet build never restores, so a separate restore is always required.
open as a page

In the .NET 10 SDK, what does NuGetAudit check during restore, how do NuGetAuditMode and NuGetAuditLevel default, and how do you fail CI on findings?

level: middleimportance: must knowfreq 50%

basics

~20 s

Restore compares every audited package against advisories from the audit sources and warns NU1901 to NU1904 by severity. NuGetAudit is true and NuGetAuditLevel is low by default; NuGetAuditMode is all for net10.0+ projects and direct otherwise. Add NU1903;NU1904 to WarningsAsErrors to fail CI.

open as a page

In NuGet, what do RestorePackagesWithLockFile and dotnet restore --locked-mode do, and why would a bank's CI pipeline restore in locked mode?

level: middleimportance: should knowfreq 45%

basics

~10 s

RestorePackagesWithLockFile makes restore write packages.lock.json with every resolved package and its content hash. --locked-mode (RestoreLockedMode) restores exactly that file and fails with NU1004 when the project's dependencies no longer match it.

open as a page

In NuGet, how are nuget.config files at repository, user and machine level combined, and how should a CI build authenticate to a private feed?

level: middleimportance: should knowfreq 42%

basics

~20 s

NuGet loads machine, user and then every nuget.config from the drive root down to the solution folder; the closest value wins and lists such as packageSources merge unless a <clear /> resets them. CI should pass feed credentials through environment variables or a credential provider, never committed clear text.

open as a page

In a nuget.config with packageSourceMapping, how does NuGet decide which source a package may come from, and what breaks when you first switch it on?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Once packageSourceMapping exists, every package, transitive ones included, may only be restored from a source whose pattern matches its id; an exact id beats the longest prefix, and * is the fallback. Unmapped packages fail restore with NU1100.

open as a page