I’ll cut to the chase: poorly versioned NuGet packages will mess up your development. Yeah, it’s kind of obvious—but have you ever really thought about why? A single NuGet package can have one of five distinct version numbers, each with its own formatting rules and behaviors. And if you’re not staying on top of how you version them, things can go sideways fast.

When your NuGet versions don’t follow SemVer, unstable packages are bound to slip into production. On the flip side, if you’re not managing your assembly version numbers right, you might not even reach production—arriving at a bunch of assembly errors instead.

In this article, we’ll look at five best practices—covering SemVer, assembly versions, and pre-release versions—compacted into five quick tips. This way, you can start versioning your NuGet packages immediately!

💡 1. Stick to SemVer for Package Version Types

NuGet packages can still use a 4-part version number like 4.3.0.0—but Microsoft doesn’t really recommend this format anymore.

Instead, stick to the tried and true Major, Minor, and Patch versioning. Sticking to this format keeps things clear and avoids confusion, making version numbers easier to understand. It also tells other developers exactly what stage of development your package is at—and whether or not it’s unstable.

💡 2. Use a Fixed Assembly Version Or Match

Before NuGet came along, assembly version numbers were how libraries figured out which version of the assembly to load at runtime. But now? NuGet just copies the assembly DLL right next to your app’s executables and deploys everything to the server.

So yeah—assembly versions aren’t really needed anymore in the current age of NuGet. By using a fixed version number (ex. 9.9.9.9) you won’t run into assembly load errors at runtime.

// Fixed version number
[assembly:AssemblyVersion("9.9.9.9")]

If a fixed version number isn’t practical, no worries—you can just match your SemVer package version and add a 0 on the fourth number.

// Package Version number 5.4.2
[assembly:AssemblyVersion("5.4.2.0")]

💡 3. Embed the Version Number in the Assembly DLL

When you’re using a fixed assembly version number along with an Assembly File Version attribute, make sure to embed the version number in the DLL. It will save you a ton of hassle when debugging—especially if you ever need to verify a library was correctly (or incorrectly) deployed.

// Package Version number 5.4.2
[assembly:AssemblyFileVersion("5.4.2")]
[assembly:AssemblyVersion("9.9.9.9")]

💡 4. Automate Building Prerelease Packages with a Build Server

Whether you’re building a NuGet package as part of a CI/CD pipeline or not, you should have your Build Server tack on a pre-release label to your package. That way, it’s communicated clearly that the library within the package is still unstable.

Pre-release labels with “dot identifiers” are a simple way to manage a package’s unique version number. There are no standards for what these identifiers need to look like, so your team can experiment to find the best, personalized solution.

One popular approach? Use a “ci” tag with either a sequence number or DateTime string—like 4.2-ci.4 or 4.2-ci.202506221023. A sequence number helps identify build order (e.g., the 4th build of version 4.2), while the DateTime string records exactly when the package was created.

💡 5. DON’T Push a Pre-release Package, even if it’s Tested

A pre-release tag helps other developers recognize that a package is unstable. So, once a pre-release package has been tested, and is confirmed stable, it’s time to push it to publication, right? Not quite. Please don’t publish packages with pre-release tags.

Pre-release tags are great for signaling to other developers that a package is unstable. So, once a pre-release package has been tested, and it’s confirmed stable, you’d think it’s time to publish, right? Nope, not quite. Please don’t push packages with pre-release tags into production!

Instead, you’ll want a way of turning prerelease packages into stable ones, ready for production. “Repackaging,” available in ProGet, creates a brand new package from your pre-release package, copying the exact same contents, just with a new version number and name.

NuGet packages are essentially zip files, so you can repackage by (basically) unzipping the package, editing the .nuspec manifest with the updated version number, and saving it as a new file. It’s like hitting “Save As”, but for packages!

Better yet, Repackaging guarantees the packages you send to production were tested.

SemVer Best Practices for NuGet

Following best practices for NuGet will help your development exponentially, especially if you’re running on, or looking to start, a CI/CD pipeline with your NuGet packages. However, neglecting proper NuGet package versioning is a surefire way to stall your CI/CD pipeline with misnamed packages and assembly errors, not to mention the unstable packages that will be in your release builds.

Start implementing these tips in your NuGet package versioning to avoid these issues and keep your package versions consistent and functional. Other steps you can take to help promote NuGet standards to your team are encouraging best authoring practices or setting up filters to avoid unwanted NuGet packages.

We covered a lot of points here, so keep these tips close by for future reference! A great way to do this would be to download our eBook, “NuGet at Scale”. It’s got everything in this article, as well as info on filtering unwanted packages, using lock files for repeatable builds, and much more! Get your free copy today!