dotnet restore --locked-mode: fail when packages.lock.json does not match

NuGet can record the exact resolved version of every direct and transitive package in packages.lock.json. dotnet restore --locked-mode restores only what that file says and fails with NU1004 if the project's package references no longer match it, instead of rewriting the file. Use it in CI so a build cannot silently resolve different versions than the ones committed. The lock file must be enabled first with RestorePackagesWithLockFile (or --use-lock-file).

Changed reference, locked restore

dotnet new classlib -o Lib > /dev/null && cd Lib
dotnet add package Newtonsoft.Json --version 13.0.3 > /dev/null
dotnet restore --use-lock-file -v q > /dev/null
ls packages.lock.json
sed -i 's/Version="13.0.3"/Version="13.0.1"/' Lib.csproj
echo "--- dotnet restore --locked-mode"
dotnet restore --locked-mode 2>&1 | grep -o "error NU1004: .*" | sed -E 's/ \[[^]]*\]$//' | head -1
echo "--- dotnet restore (updates the lock file)"
dotnet restore -v q > /dev/null; echo "exit: $?"
grep -A4 '"Newtonsoft.Json"' packages.lock.json | grep resolved
dotnet restore --locked-mode -v q > /dev/null; echo "locked again, exit: $?"

packages.lock.json
--- dotnet restore --locked-mode
error NU1004: The package reference Newtonsoft.Json version has changed from [13.0.3, ) to [13.0.1, ).The packages lock file is inconsistent with the project dependencies so restore can't be run in locked mode. Disable the RestoreLockedMode MSBuild property or pass an explicit --force-evaluate option to run restore to update the lock file.
--- dotnet restore (updates the lock file)
exit: 0
        "resolved": "13.0.1",
locked again, exit: 0

After the version in the project file changed, locked mode refuses to restore and explains which references differ. A normal restore rewrites packages.lock.json, and locked mode passes again.

Options and properties

dotnet build and dotnet test restore implicitly and accept the same options (dotnet build --locked-mode), or use --no-restore after an explicit locked restore.

CI setup

dotnet restore --locked-mode
dotnet build --no-restore -c Release
dotnet test --no-build -c Release

With central package management (Directory.Packages.props) each project still has its own packages.lock.json; changing a central version invalidates every lock file that uses the package.

Pitfalls

• A lock file generated for one set of runtime identifiers fails on another; include every RID you restore for in RuntimeIdentifiers.
• Different SDK versions may write different lock files for the same project. Pin the SDK with global.json.
• NU1004 can also appear when a project reference adds packages; restore the whole solution and commit every changed packages.lock.json.
• Downgrades are still reported separately as NU1605; other codes are listed in NuGet error codes.

FAQ