NuGet dependency resolution limits: nearest wins behavior

Direct Answers

• Nearest-wins triggers when the same package ID appears at multiple depths in the transitive dependency graph. The version on the shortest path from the root project (fewest edges) is chosen, regardless of whether it is lower or higher than versions on longer paths.
• Lock file guarantee: A lock file (project.assets.json or solution-level packages.lock.json) pins the exact versions resolved during a successful restore. It does not re-run nearest-wins on subsequent restores. All projects that share the same lock file (or have compatible lock files) will use identical versions, even if a fresh nearest-wins calculation would differ.
• Explicit higher version override: A top-level PackageReference with a higher version overrides nearest-wins because it sits at depth zero — the shortest possible path. This is not a special exception; it is the nearest-wins rule applied to the direct reference.

How Nearest-Wins Works

NuGet builds a dependency graph per project. When the same package ID is reachable via multiple paths, the algorithm measures the distance (number of edges) from the root project to each occurrence. The version at the minimal distance wins. If two paths have equal depth, the tie-break is deterministic but undocumented (typically the first encountered).

This rule applies during the initial restore. Once a lock file exists, the resolver honors the locked versions and skips the graph walk for those packages.

Lock File Scope and Cross-Project Consistency

• Per-project lock files (project.assets.json) are independent. Restoring each project separately can yield different versions for the same transitive package.
• Solution-level lock file (packages.lock.json) is enabled via nuget.config (config > lockFilePath) or Directory.Build.props (RestorePackagesWithLockFile=true). When active, all projects in the solution read the same locked graph, guaranteeing version consistency.
• NuGet 6.0+ (SDK 6.0+) emits warning NU1507 when projects in a solution have mismatched lock files, but does not auto-reconcile.

Explicit Version Overrides

• A direct PackageReference in the project file is at depth zero, so it always wins over any transitive occurrence.
• Central Package Management (Directory.Packages.props) places every PackageReference at the solution level, making all references depth-zero. Nearest-wins effectively disappears; conflicts become explicit version mismatches that must be resolved in the central file.
• DependencyVersion settings in nuget.config (Lowest, Highest, HighestMinor, HighestPatch) affect the initial resolution before locking. Once locked, they have no effect until the lock file is cleared.

Verification Steps (Safe Commands)

1. Create a minimal solution:

   dotnet new sln -n NearestWinsDemo
   mkdir ProjectA ProjectB
   cd ProjectA && dotnet new classlib
   cd ../ProjectB && dotnet new classlib
   cd ..
   

2. Add divergent references:

   dotnet add ProjectA/ProjectA.csproj package Newtonsoft.Json --version 12.0.3
   dotnet add ProjectB/ProjectB.csproj package Newtonsoft.Json --version 13.0.1
   dotnet add ProjectB/ProjectB.csproj reference ProjectA/ProjectA.csproj
   

3. Restore and inspect per-project lock files:

   dotnet restore
   cat ProjectA/obj/project.assets.json | grep -A2 -B2 'Newtonsoft.Json'
   cat ProjectB/obj/project.assets.json | grep -A2 -B2 'Newtonsoft.Json'
   

   Observe which version each project resolves (nearest-wins picks 12.0.3 for ProjectA, 13.0.1 for ProjectB).
4. Enable solution-level lock file and restore again:

   dotnet new nugetconfig
   # Edit nuget.config: add <config><add key="lockFilePath" value="packages.lock.json" /></config>
   dotnet restore --force
   cat packages.lock.json | grep -A2 -B2 'Newtonsoft.Json'
   

   Both projects now read the same locked version.
5. Add a direct higher reference to ProjectA, clear locks, and restore:

   dotnet add ProjectA/ProjectA.csproj package Newtonsoft.Json --version 14.0.0
   rm -f ProjectA/obj/project.assets.json ProjectB/obj/project.assets.json packages.lock.json
   dotnet restore
   

   ProjectA now resolves 14.0.0 (depth-zero wins).

Assumptions and Uncertainty

• Behavior described applies to .NET SDK-style projects (PackageReference) with NuGet 5.0+ / .NET Core 3.1+. Legacy packages.config uses a different resolver.
• Tie-breaking for equal-depth paths is not publicly documented; treat it as implementation-defined.
• PrivateAssets=all suppresses transitive flow, which can create diamond graphs where nearest-wins picks a version invisible to some consumers.
• Floating versions (e.g., 1.*) are resolved once and then locked; the locked concrete version participates in nearest-wins like any other pinned version.

One Diagnostic Detail That Changes Recommendation

Are you using a solution-level packages.lock.json (enabled via nuget.config or Directory.Build.props) or relying on per-project project.assets.json files? The answer determines whether cross-project version consistency is guaranteed.