skip to content

PackageReference & Versions

How a project declares NuGet dependencies: PackageReference ranges, transitive picks by lowest-applicable and direct-dependency-wins, and Central Package Management. Asked to explain version drift.

on this pageshow

explore

questions

5

In a .NET project file, what does <PackageReference Include="Serilog" Version="4.4.0" /> ask NuGet for, and how do [4.4.0], [4.0,5.0) and 4.* change it?

level: juniorimportance: must knowfreq 68%

answer

  1. a bare version is a floor
  2. lowest applicable version wins
  3. square bracket inclusive, parenthesis exclusive
  4. the asterisk floats to the highest match
  5. dotnet package add writes latest stable

basics

~20 s

A bare Version="4.4.0" means 4.4.0 or higher, and NuGet restores the lowest version that satisfies it. [4.4.0] pins exactly, [4.0,5.0) bounds the range and still takes its lowest member, and 4.* floats to the highest 4.x.

solid answer

~40 s

In NuGet, `Version="4.4.0"` on a `PackageReference` is a **minimum**, not a pin: it means `>= 4.4.0`, and restore applies the **lowest applicable version** rule, so it picks 4.4.0 if the feed has it, even when 4.5.0 exists. `[4.4.0]` is an exact match and fails restore if that version is missing. `[4.0,5.0)` accepts 4.0 up to but excluding 5.0 and still resolves to the lowest version in the range. `4.*` is a **floating** version: restore takes the highest stable 4.x it finds, so the result can change when a new package is pushed. `dotnet package add Serilog` with no version writes the latest stable release as a bare minimum, which the lowest-applicable rule then keeps until someone edits the file.

code

xml · 10 lines
xml
<ItemGroup>
  <!-- 4.4.0 or higher; restore takes the lowest available -->
  <PackageReference Include="Serilog" Version="4.4.0" />
  <!-- exactly 10.0.3, restore fails if it is missing -->
  <PackageReference Include="Npgsql" Version="[10.0.3]" />
  <!-- 8.0 up to but excluding 9.0; still the lowest match -->
  <PackageReference Include="Polly.Core" Version="[8.0,9.0)" />
  <!-- floating: the highest stable 12.x on the feeds -->
  <PackageReference Include="FluentValidation" Version="12.*" />
</ItemGroup>

go deeper

for a junior

Recall that a bare version is a minimum, that [x] is exact, and that dotnet package add writes the latest stable release for you.

for a middle

Explain lowest applicable versus floating resolution, what NU1601 and NU1604 mean, and how prereleases are only considered when something in the graph asks for one.

for a senior

Show judgement about exact pins and upper bounds: they create unsolvable graphs and block fixes, so you reserve them for proven incompatibilities and keep floors honest.

for a principal

Frame the trade-off between repeatable restores and staying current, and how floors, floating versions and lock files combine into a repository-wide upgrade policy.

## What the Version attribute actually says A `PackageReference` item in a `.csproj` names a NuGet package and a **version range**. The surprise for most newcomers is that a plain version number is already a range. NuGet's versioning reference lists `1.0` as `x >= 1.0` — "minimum version, inclusive". So this line in an accounting service: ```xml <PackageReference Include="Serilog" Version="4.4.0" /> ``` does **not** say "use exactly 4.4.0". It says "anything from 4.4.0 upward is acceptable", and leaves the choice to restore. ## The notation NuGet accepts NuGet uses interval notation: a square bracket includes the endpoint, a parenthesis excludes it. | Version attribute | Meaning | What restore picks | |---|---|---| | `4.4.0` | x >= 4.4.0 | the lowest version >= 4.4.0 on the feeds | | `[4.4.0]` | x == 4.4.0 | 4.4.0, or a restore error if it is missing | | `[4.0,5.0)` | 4.0 <= x < 5.0 | the lowest version in the range | | `(4.1.3,)` | x > 4.1.3 | the lowest version above 4.1.3 | | `4.*` | floating, any 4.x | the **highest** stable 4.x | | `4.*-*` | floating, prereleases included | the highest 4.x, prerelease or not | `(1.0)` is invalid. An upper bound such as `(,5.0)` is legal but the docs advise against upper bounds on packages you do not own, because they block consumers from receiving fixes. ## Which version restore actually picks Two different rules apply, and mixing them up is the classic mistake: - **Lowest applicable version.** For every non-floating range, restore takes the smallest version that satisfies it. If the floor itself is not on any feed, it takes the next lowest one it can find and warns with **NU1601**. An exact `[4.4.0]` that is missing cannot be substituted, so restore fails. - **Floating versions.** Only a version containing `*` makes restore look for the highest match. `4.*` therefore moves when a new 4.x is pushed, which is why the docs pair floating versions with lock files for repeatability. - **Prereleases.** Restore considers prerelease versions only when the project or some package in the graph asks for one. With `[1.0.0, 2.0.0)` and only `1.2.0-beta.1` available, restore fails with NU1103 instead of taking the beta. The lowest-applicable rule is deliberate: the build you get today is the build you get next month, until someone changes the project file. The flip side is that nothing upgrades on its own; a newer patch on nuget.org changes nothing until the floor moves. ## How the reference usually gets there With the .NET 10 SDK the command is the noun-first `dotnet package add`, an alias of the older `dotnet add package`: 1. `dotnet package add Serilog` asks the feeds for the latest **stable** version and writes it as a bare minimum, for example `Version="4.4.0"`. 2. `--version 4.4.0`, or the `[email protected]` form, writes the value you give; passing both is rejected. 3. `--prerelease` lets the command choose a prerelease when it looks up the latest version. 4. The command runs a restore preview before it writes anything; if the package is compatible with none of the project's target frameworks, the project file is left untouched. If the package is already referenced, the command updates the existing `PackageReference` rather than adding a second one. ## Why exact pins and upper bounds bite An exact pin looks safe in one place and becomes a trap in a graph. If one library the accounting suite uses depends on exactly `[10.0.3]` of a package and another requires `>= 10.0.4` of it, no single version satisfies both and restore stops with **NU1107**, a version conflict, until the application adds its own direct reference. Had the first library declared a bare minimum, the higher requirement would simply have won. The same logic applies to upper bounds: `[8.0,9.0)` on a package you do not own blocks the 9.x fix your consumers may need, and NuGet's own guidance is to add an upper bound only when you know of a real incompatibility. Versions are also normalised: `4.4` and `4.4.0` denote the same version, and a version can be written as a `<Version>` child element instead of an attribute with the same meaning. ## Practical guidance - Always give a version. A `PackageReference` with no lower bound raises **NU1604**, and restore then goes online on every run looking for the lowest version. - Use a bare minimum for applications and libraries alike; use `[x]` only when you truly cannot accept anything else, because exact pins are what produce unsolvable conflicts. - Treat `*` as a choice to accept whatever is pushed next, not as a convenience. - To see what you really got, `dotnet package list` prints a **Requested** column (your range) beside a **Resolved** column (the single version restore chose).

  • What happens if Version="4.4.0" is requested but only 4.4.1 and 4.5.0 exist on the feeds?
    Restore takes the next lowest version that satisfies the floor, 4.4.1, and warns with NU1601 that the dependency asked for 4.4.0 but ended up with 4.4.1. If the reference had been the exact range `[4.4.0]`, no substitute is allowed and restore fails because the version cannot be found.
  • Why does NuGet prefer the lowest applicable version over the newest one?
    It makes restore repeatable: the version you named is the version you get on every machine, and a package pushed tomorrow cannot change today's build. The cost is that upgrades are explicit — a new patch on the feed is ignored until someone raises the floor, which is the usual source of version drift.
  • When does a floating version like 12.* earn its place?
    In a project that wants to track the newest release of a package automatically, accepting that the restored version can change between two runs. NuGet's docs recommend enabling lock files alongside floating versions so a given commit still restores the same graph.

  • Version="4.4.0" pins the project to exactly 4.4.0.
  • NuGet always restores the newest version that a range allows.
  • A floating 4.* resolves to the lowest 4.x on the feed.
  • [4.0,5.0) includes 5.0.0 because both ends of a range are inclusive.
  • dotnet package add writes Version="*" so the project stays current.

Assumes NuGet 7 in the .NET 10 SDK; dotnet package add is the noun-first alias that .NET 10 added for dotnet add package, and the range and lowest-applicable rules are unchanged from earlier NuGet releases.

open as a page

In NuGet's Central Package Management, how would you move the 25 projects of an accounting suite onto one Directory.Packages.props, and which errors catch leftovers?

level: middleimportance: must knowfreq 55%

basics

~20 s

Add a Directory.Packages.props at the repository root with ManagePackageVersionsCentrally set to true and one PackageVersion per package, then strip Version from every PackageReference. Restore raises NU1008 for a leftover Version and NU1010 for a reference without a PackageVersion.

open as a page

In a .NET PackageReference, what do IncludeAssets, ExcludeAssets and PrivateAssets control, and why do analyzer packages usually get PrivateAssets="all"?

level: middleimportance: should knowfreq 38%

basics

~20 s

IncludeAssets and ExcludeAssets decide which parts of a package this project consumes; PrivateAssets decides which parts stop here instead of flowing to projects or packages that depend on it. PrivateAssets="all" makes a development-only package invisible to consumers.

open as a page

In a .NET project restored by NuGet, why does a transitive package stay on an older patch, and when does a direct PackageReference cause NU1605?

level: middleimportance: should knowfreq 50%

basics

~20 s

Restore gives each transitive package the lowest version that satisfies every range, so it stays on the floor a dependency declared. A direct PackageReference overrides deeper requests, and if it is lower NuGet reports NU1605, which C# SDK projects treat as an error.

open as a page

In NuGet's Central Package Management, when would you use VersionOverride, CentralPackageTransitivePinningEnabled or GlobalPackageReference, and what does each one cost you?

level: seniorimportance: should knowfreq 28%

basics

~20 s

VersionOverride lets one PackageReference ignore the central version. CentralPackageTransitivePinningEnabled makes PackageVersion entries also raise transitive packages, at the price of NU1109 on downgrades and extra pack dependencies. GlobalPackageReference adds a build-only package to every project.

open as a page