/flags/nuget/dotnet-add-package-prerelease
dotnet add package --prerelease: install the latest preview version
- tool
- NuGet
- command
- dotnet add package
- flag
- --prerelease
- default
- off (the latest stable version is added)
dotnet add package NAME adds the latest stable version of a package. If the package only has newer previews, betas or release candidates (versions with a suffix such as -preview.1 or -rc.2), they are ignored. dotnet add package NAME --prerelease includes them, so the newest version overall is added. To pin a particular prerelease, --version 2.0.0-beta.1 works without the flag.
Stable by default, prerelease on request
A local feed contains Demo.Lib 1.0.0 and 2.0.0-beta.1:
dotnet new classlib -o Demo.Lib > /dev/null
dotnet pack Demo.Lib -o feed -p:PackageVersion=1.0.0 -v q -nologo > /dev/null 2>&1
dotnet pack Demo.Lib -o feed -p:PackageVersion=2.0.0-beta.1 -v q -nologo > /dev/null 2>&1
ls feed
dotnet new console -o app > /dev/null && cd app
echo "--- dotnet add package Demo.Lib"
dotnet add package Demo.Lib -s ../feed > /dev/null; grep "Demo.Lib" app.csproj
echo "--- dotnet add package Demo.Lib --prerelease"
dotnet add package Demo.Lib -s ../feed --prerelease > /dev/null; grep "Demo.Lib" app.csprojOutput
Demo.Lib.1.0.0.nupkg
Demo.Lib.2.0.0-beta.1.nupkg
--- dotnet add package Demo.Lib
<PackageReference Include="Demo.Lib" Version="1.0.0" />
--- dotnet add package Demo.Lib --prerelease
<PackageReference Include="Demo.Lib" Version="2.0.0-beta.1" />The first call picks 1.0.0 even though 2.0.0-beta.1 is newer. With --prerelease, the reference is updated to the beta. The -s option limits the lookup to the local folder, see dotnet restore --source.
Version selection
| Command | Version added |
|---|---|
| dotnet add package Demo.Lib | Latest stable (1.0.0) |
| dotnet add package Demo.Lib --prerelease | Latest including prereleases (2.0.0-beta.1) |
| dotnet add package Demo.Lib --version 2.0.0-beta.1 | Exactly that version |
| dotnet add package Demo.Lib --version "2.*-*" | Floating range that allows prereleases |
| dotnet list package --outdated --include-prerelease | Show newer prereleases of referenced packages |
How NuGet orders prereleases
NuGet follows SemVer 2.0: 2.0.0-alpha < 2.0.0-beta.1 < 2.0.0-beta.2 < 2.0.0-rc.1 < 2.0.0. Labels are compared alphabetically and numeric parts numerically, so beta.10 is newer than beta.2, while a label without dots such as beta10 is compared as text. Every prerelease of 2.0.0 is older than the stable 2.0.0.
Pitfalls
- A version range like
[1.0,2.0)written by hand does not include prereleases of 1.x unless the lower bound itself is a prerelease. - Library authors: a package that depends on a prerelease must itself be a prerelease, otherwise
dotnet packwarns (NU5104). - Asking for a prerelease version that does not exist fails with NU1102, which lists the nearest versions available.
- Checking for updates later is done with dotnet list package --outdated, which also ignores prereleases unless asked.
FAQ
Why does dotnet add package install an older version than the one on nuget.org?
The newest version is a prerelease (for example 2.0.0-preview.3) and dotnet add package picks the latest stable version by default. Add --prerelease, or name the version with --version.
Can I add a prerelease with --version instead?
Yes. dotnet add package Demo.Lib --version 2.0.0-beta.1 installs exactly that prerelease; --prerelease is only needed when you want whatever the newest one is.
Does --prerelease affect transitive dependencies?
No. It only changes which version of the package you name is chosen. Dependencies follow their declared version ranges, and NuGet still prefers stable versions there.