Package versioning

A specific package is always referred to using its package identifier and an exact version number. For example, Entity Framework on nuget.org has several dozen specific packages available, ranging from version 4.1.10311 to version 6.1.3 (the latest stable release) and a variety of pre-release versions like 6.2.0-beta1.

When creating a package, you assign a specific version number with an optional pre-release text suffix. When consuming packages, on the other hand, you can specify either an exact version number or a range of acceptable versions.

In this topic:

Version basics

A specific version number is in the form Major.Minor.Patch[-Suffix], where the components have the following meanings:

  • Major: Breaking changes
  • Minor: New features, but backwards compatible
  • Patch: Backwards compatible bug fixes only
  • -Suffix (optional): a hyphen followed by a string denoting a pre-release version (following the Semantic Versioning or SemVer 1.0 convention).

Examples:

1.0.1           
6.11.1231
4.3.1-rc
2.2.44-beta1
Important

nuget.org rejects any package upload that lacks an exact version number. The version must be specified in the .nuspec or project file used to create the package.

Pre-release versions

Technically speaking, package creators can use any string as a suffix to denote a pre-release version, as NuGet treats any such version as pre-release and makes no other interpretation. That is, NuGet displays the full version string in whatever UI is involved, leaving any interpretation of the suffix's meaning to the consumer.

That said, package developers generally follow recognized naming conventions:

  • -alpha: Alpha release, typically used for work-in-progress and experimentation.
  • -beta: Beta release, typically one that is feature complete for the next planned release, but may contain known bugs.
  • -rc: Release candidate, typically a release that's potentially final (stable) unless significant bugs emerge.
Note

NuGet 4.3.0+ supports SemVer 2.0.0, which supports pre-release numbers with dot notation, as in 1.0.1-build.23. Dot notation is not supported with NuGet versions before 4.3.0. You can use a form like 1.0.1-build23.

When resolving package references and multiple package versions differ only by suffix, NuGet chooses a version without a suffix first, then applies precedence to pre-release versions in reverse alphabetical order. For example, the following versions would be chosen in the exact order shown:

1.0.1           
1.0.1-zzz
1.0.1-rc
1.0.1-open
1.0.1-beta
1.0.1-alpha2
1.0.1-alpha
1.0.1-aaa

Semantic Versioning 2.0.0

With NuGet 4.3.0+ and Visual Studio 2017 version 15.3+, NuGet supports Semantic Versioning 2.0.0.

Certain semantics of SemVer v2.0.0 are not supported in older clients. NuGet considers a package version to be SemVer v2.0.0 specific if either of the following statements is true:

  • The pre-release label is dot-separated, for example, 1.0.0-alpha.1
  • The version has build-metadata, for example, 1.0.0+githash

For nuget.org, a package is defined as a SemVer v2.0.0 package if either of the following statements is true:

  • The package's own version is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, as defined above.
  • Any of the package's dependency version ranges has a minimum or maximum version that is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, defined above; for example, [1.0.0-alpha.1, ).

If you upload a SemVer v2.0.0-specific package to nuget.org, the package is invisible to older clients and available to only the following NuGet clients:

  • NuGet 4.3.0+
  • Visual Studio 2017 version 15.3+
  • dotnet.exe (.NET SDK 2.0.0+)

Third-party clients:

  • JetBrains Rider
  • Paket version 5.0+

Version ranges and wildcards

When referring to package dependencies, NuGet supports using interval notation for specifying version ranges, summarized as follows:

Notation Applied rule Description
1.0 1.0 ≤ x Minimum version, inclusive
(1.0,) 1.0 < x Minimum version, exclusive
[1.0] x == 1.0 Exact version match
(,1.0] x ≤ 1.0 Maximum version, inclusive
(,1.0) x < 1.0 Maximum version, exclusive
[1.0,2.0] 1.0 ≤ x ≤ 2.0 Exact range, inclusive
(1.0,2.0) 1.0 < x < 2.0 Exact range, exclusive
[1.0,2.0) 1.0 ≤ x < 2.0 Mixed inclusive minimum and exclusive maximum version
(1.0) invalid invalid

When using the PackageReference or project.json package reference formats, NuGet also supports using a wildcard notation, *, for Major, Minor, Patch, and pre-release suffix parts of the number. Wildcards are not supported with the packages.config format.

Note

Pre-release versions are not included when resolving version ranges. Pre-release versions are included when using a wildcard (*). The version range [1.0,2.0], for example, does not include 2.0-beta, but the wildcard notation 2.0-* does. However, due to issues issue 912, 4513, and 4859, the wildcard notation resolves the lowest matching version, not the latest. There is presently no means to resolve the latest version.

Examples

Important

Always specify a version or version range for package dependencies. Without a version or version range, NuGet 2.8.x and earlier chooses the latest available package version when resolving a dependency, whereas NuGet 3.x and later chooses the lowest package version. Specifying a version or version range avoids this uncertainty.

References in project files:

<!-- Accepts any version 6.1 and above -->
<PackageReference Include="ExamplePackage" Version="6.1" />

<!-- Accepts any version 6.x.y version -->
<PackageReference Include="ExamplePackage" Version="6.*" />

<!-- Accepts any version above, but not include 4.1.3. This might be
      used to guarantee a dependency with a specific bug fix. -->
<PackageReference Include="ExamplePackage" Version="(4.1.3,)" />

<!-- Accepts any version up below 5.x, which might be used to prevent
      pulling in a later version of a dependency that changed its interface.
      However, this form is not recommended because it can be difficult to
      determine the lowest version.  -->
<PackageReference Include="ExamplePackage" Version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but no 0.x or 3.x and higher versions -->
<PackageReference Include="ExamplePackage" Version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher. -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher. -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />

References in packages.config:

<!-- Accepts any version 6.1 and above -->
<dependency id="ExamplePackage" version="6.1" />

<!-- Accepts any version 6.x.y version -->
<dependency id="ExamplePackage" version="6.*" />

<!-- Accepts any version above, but not include 4.1.3. This might be
      used to guarantee a dependency with a specific bug fix. -->
<dependency id="ExamplePackage" version="(4.1.3,)" />

<!-- Accepts any version up below 5.x, which might be used to prevent
      pulling in a later version of a dependency that changed its interface.
      However, this form is not recommended because it can be difficult to
      determine the lowest version.  -->
<dependency id="ExamplePackage" version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but no 0.x or 3.x and higher versions -->
<dependency id="ExamplePackage" version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher. -->
<dependency id="ExamplePackage" version="[1.3.2,1.5)" />

Normalized version numbers

Note

This is a breaking change for NuGet 3.4 and later.

When obtaining packages from a repository during install, reinstall, or restore operations, NuGet 3.4+ treats version numbers as follows:

  • Leading zeroes are removed from version numbers:

    1.00 is treated as 1.0
    1.01.1 is treated as 1.1.1
    1.00.0.1 is treated as 1.0.0.1
    
  • A zero in the fourth part of the version number will be omitted

    1.0.0.0 is treated as 1.0.0
    1.0.01.0 is treated as 1.0.1
    

This normalization does not affect the version numbers in the packages themselves; it affects only how NuGet matches versions when resolving dependencies.

However, NuGet package repositories must treat these values in the same way as NuGet to prevent package version duplication. Thus a repository that contains version 1.0 of a package should not also host version 1.0.0 as a separate and different package.