Building pre-release packages

Whenever you release an updated package with a new version number, NuGet considers that one as the "latest stable release" as shown, for example in the Package Manager UI within Visual Studio:

Package Manager UI showing the latest stable release

A stable release is one that's considered reliable enough to be used in production. The latest stable release is also the one that will be installed as a package update or during package restore (subject to constraints as described in Reinstalling and updating packages).

To support the software release lifecycle, NuGet 1.6 and later allows for the distribution of pre-release packages, where the version number includes a semantic versioning suffix such as -alpha, -beta, or -rc. For more information, see Package versioning.

You can specify such versions using one of the following ways:

  • If your project uses PackageReference: include the semantic version suffix in the .csproj file's PackageVersion element:

  • If your project has a packages.config file: include the semantic version suffix in the .nuspec file's version element:


When you're ready to release a stable version, just remove the suffix and the package takes precedence over any pre-release versions. Again, see Package versioning.

Installing and updating pre-release packages

By default, NuGet does not include pre-release versions when working with packages, but you can change this behavior as follows:

  • Package Manager UI in Visual Studio: In the Manage NuGet Packages UI, check the Include prerelease box:

    The Include prerelease checkbox in Visual Studio

    Setting or clearing this box will refresh the Package Manager UI and the list of available versions you can install.

  • Package Manager Console: Use the -IncludePrerelease switch with the Find-Package, Get-Package, Install-Package, Sync-Package, and Update-Package commands. Refer to the PowerShell Reference.

  • NuGet CLI: Use the -prerelease switch with the install, update, delete, and mirror commands. Refer to the NuGet CLI reference

Semantic versioning

The Semantic Versioning or SemVer convention describes how to utilize strings in version numbers to convey the meaning of the underlying code.

In this convention, each version has three parts, Major.Minor.Patch, with the following meaning:

  • Major: Breaking changes
  • Minor: New features, but backwards compatible
  • Patch: Backwards compatible bug fixes only

Pre-release versions are then denoted by appending a hyphen and a string after the patch number. Technically speaking, you can use any string after the hyphen and NuGet will treat the package as pre-release. NuGet then displays the full version number in the applicable UI, leaving consumers to interpret the meaning for themselves.

With this in mind, it's generally good to follow recognized naming conventions such as the following:

  • -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.


NuGet 4.3.0+ supports Semantic Versioning v2.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. In earlier versions of NuGet, you could use a form like 1.0.1-build23 but this was always considered a pre-release version.

Whatever suffixes you use, however, NuGet will give them precedence in reverse alphabetical order:


As shown, the version without any suffix will always take precedence over pre-release versions.

Leading 0s are not needed with semver2, but they are with the old version schema. If you use numerical suffixes with pre-release tags that might use double-digit numbers (or more), use leading zeroes as in beta.01 and beta.05 to ensure that they sort correctly when the numbers get larger. This recommendation only applies to the old version schema.