This article is part of a series on Chocolatey for the Enterprise, also available as a chapter in our free, downloadable eBook

Chocolatey package versioning seems simple at first but can quickly get confusing. Take a look at Chocolatey.org and you may see versions like “7.1.0” at first, but then something like “4.8 4.8.0.20220524” elsewhere. The formats aren’t exactly consistent.

If you use choco install «package» Chocolatey will install the latest version of the package. So, to install a particular version you’ll need to give the version number, but what exactly are you supposed to type for version 4.8.1 4.8.1.0-rtw?? 

In this article, I’ll break down how versioning works in Chocolatey, as well as pass on some best practices for versioning your internal Chocolatey packages. 

Chocolatey Versioning 101 

Typically, Chocolatey packages use “semantic versioning“, which is just a fancy way of saying the version number is split into major, minor, and patch parts (like 2.3.1). But you’re going to find that’s not always the case. Chocolatey versioning isn’t super strict, and even recommends sticking with the software’s version number. So, you’ll see packages with all kinds of formats, Like Microsoft .NET Framework version 4.8.1 4.8.1.0-rtw. 

Package authors will often assign packages with version numbers that align with the software they are packaging as it’s a good practice that keeps things simple, like this example of Mozilla Firefox 127.0.2:

However, a common mistake is thinking package versions are the same as software versions. This isn’t set in stone. For example, version 3.3.3.1 of the Ruby package installs Ruby 3.3.3.

And then you have some cases where “semver” and software release versions don’t even align at all! .NET versions are a good example of this. The “dotnetfx” package “4.8.1.0-rtw” looks like a pre-release, but in this case, it’s not. To know how they align, you’ll need to read the package and release notes. 

In the case of 4.8.1.0-rtw, the release notes clarified that the package uses “prerelease suffix to prevent automatic installation on systems older than Win 10 20H2 / Server 2022.”

Package Fix Version Notation 

Once a package is uploaded to Chocolatey, it can’t be deleted. This means that, if you need to make changes to the package itself — such as fixing a bug in the installation script, updating a URL for a file download, or adding a silent installation option — you need to upload a new package. And that package needs a different version number.

This is where Chocolatey’s package fix notation comes in. The format for this notation is the version number followed by the date in YYYYMMDD format. This lets you create a new package, while installing the same version.

For example, Winrar package version 6.11.0.20220504 is a fix that installs Winrar 6.11. 

Handling Versions in Chocolatey 

Running choco install «package» will install the latest version of a package. However, it’s better to install specific versions. This will avoid any issues caused by unexpected changes to the software. 

To do this you’ll use --version=. But if you try with packages like Microsoft .NET Framework 4.8 4.8.0.0-rtw4, running choco install dotnexfx --version=4.8 4.8.0.0-rtw4 simply won’t work.

To know what to enter you’ll have to check the install instructions:

A way to get around these version issues is to use a private repository like ProGet, rather than rely on packages directly from Chocolatey.org. By hosting your own private repository, you have full control over the package versions used in your development. This lets you make sure packages remain consistent and free from unexpected updates that could mess with your environment. 

Keep an eye out for Version Normalization 

Behind the scenes, Chocolatey is based on a packaging technology called NuGet and therefore uses NuGet’s versioning rules and behavior. This can lead to some unexpected behavior called version normalization.

Version normalization seems quirky at first, since the version you upload to a Chocolatey repository will appear to be different than the package version.

• If your version number has two parts (e.g. 1.4), then it will be treated as a three-part version (e.g. 1.4.0) with an added zero
• If your version has four parts and the fourth part is zero (e.g. 4.2.5.0), it will be treated as a three-part version (e.g. 4.2.5)
• If your version parts have leading zeros (e.g. 1.001.2), it will be treated as if it didn’t (e.g. 1.1.2)

These normalized versions are used when listing and installing packages.

⚠ What this means is you should avoid creating versions like 5.0, 1.2.3.0, 7.0005.1, 4.2.1.0 as they will appear to be different. This is probably why you see packages, like Ruby 3.3.3.1, instead of 3.3.3.0.

This is why you see packages like Ruby 3.3.3.1; it’s the first “version” of the package that installs Ruby 3.3.3, but if they started it at “0” (i.e. 3.3.3.0), then it would be normalized.

Best Practices for Chocolatey Packages 

If you’re using Chocolatey in your organization and want to use your own internal packages, there are some best practices to follow based around what we talked about in this article. 

✔ Whenever possible, align the Chocolatey package version with the software version. 

✔ If not, at the very least use semantic versioning: major.minor.patch (e.g., 1.2.3). 

✔ Perhaps most importantly, clearly note any version mismatches in the package details!

Package Versioning In Chocolatey 

Chocolatey package versions can be pretty confusing. They’re not always intuitive and can include a bunch of different parts. In some cases, package versions might not even match the software version. 

The good news is you can get around this by aligning package versions with the software and using fixed version notation. You can also use a private repository like ProGet to add an extra layer of control to the versions you use in your development. 

This is a lot to digest, and I suggest keeping it handy as a reference. Or, check out our guide Chocolatey for the Enterprise, a free eBook where I’ve put together this info along with other Chocolatey best practices, such as software distribution, package privatization, offline environments, and more, so you can optimize using Chocolatey in your organization. Sign up for your free copy today!