Pin Chocolatey Package Versions: Control Updates

The convenience of using a package manager like Chocolatey for keeping your Windows software updated is undeniable. A simple command like choco upgrade all can sweep through your installed applications and bring them up to their latest versions with minimal effort.

However, in certain scenarios, this automatic update behavior might not always be desirable. You might have a critical application that requires a specific version for compatibility reasons, or you might need to maintain stability in a production environment where unexpected updates could introduce issues. This is where controlling updates becomes essential, and Chocolatey offers a powerful feature called “pinning” to achieve this. In this post, we’ll dive into what it means to Chocolatey pin package version, why you would need to do it, and how to use the choco pin command to manage your software updates precisely.

What Does It Mean to “Pin” a Package?

Pinning a package in Chocolatey means marking a specific installed package, identified by its Package ID and potentially a specific version, so that Chocolatey’s standard upgrade command will ignore it. Even if a newer version of the pinned package is available in your configured sources, choco upgrade all or choco upgrade will skip it.

Think of it as placing a temporary lock on that package version. It effectively “locks” the package to its current state as far as the automatic upgrade process is concerned.

It’s important to clarify what pinning doesn’t do. Pinning does not prevent you from manually installing a different version of the package using choco install --version or uninstalling the package entirely with choco uninstall . Its effect is specifically limited to preventing upgrades via the choco upgrade command.

Why Would You Pin a Package Version?

There are several compelling reasons why you might need to prevent automatic updates for specific software:

– Stability in Production/Critical Environments: For applications central to your workflow or business operations, unexpected updates can introduce instability. Pinning ensures these core applications remain at a known, stable version.

– Compatibility: Newer versions of software can sometimes break compatibility with plugins, extensions, scripts, or other integrated applications. Pinning allows you to maintain a version that is known to work with your existing setup.

– Testing: When evaluating a new version of a critical application, you might want to pin the currently used version on your main system while testing the newer version in a separate environment or virtual machine. This prevents an accidental upgrade on your primary setup.

– Specific Features: Occasionally, features are removed or changed in newer versions of software. Pinning allows you to stick to a version that still includes a required feature.

– Avoiding Breaking Changes: Some updates introduce significant changes to configuration, user interface, or behavior that require time to adapt to. Pinning lets you defer these updates until you are ready to handle the breaking changes.

– Dependency Requirements: While pinning a package doesn’t automatically pin its dependencies, sometimes a piece of software requires a very specific version of another component. Pinning can be part of a broader strategy to ensure all components meet exact version requirements, though dependency management is a complex topic.

Overall, pinning is a key tool for maintaining software stability and gaining granular control over your Chocolatey updates, especially in managed or sensitive environments.

Using the choco pin Command

Chocolatey provides a dedicated command, choco pin, specifically for managing package pins. This command has several subcommands to add, list, remove, and check the status of your pinned packages.

Crucial Note: Adding or removing package pins modifies Chocolatey’s global configuration. Therefore, you must run the choco pin add and choco pin remove commands with Administrator privileges. Running choco pin list or choco pin outdated typically does not require elevated permissions.

choco pin add: Pin an Installed Package

This subcommand is used to add a package to the list of pinned packages. You specify the package by its ID.

Syntax:

choco pin add -n <packageID> [--version <version>]

Explanation:

Use -n or --name followed by the Package ID. If you omit the --version option, Chocolatey will pin the currently installed version of the package. It’s often recommended to explicitly use --version for clarity, especially if you might have multiple versions of a package installed (though this is less common with most software packages).

Example: Pin googlechrome at a specific version, say 120.0.6099.71.

First, let’s check the currently installed version (requires Administrator for list --localonly in some configurations, but often works without):

choco list googlechrome --localonly

Example Output:

googlechrome 120.0.6099.71
1 packages installed.

Now, pin it using the specific version (Run this command As Administrator):

choco pin add -n googlechrome --version 120.0.6099.71

Example Output:

googlechrome v120.0.6099.71 pinned.

Example: Pin the currently installed version of vlc (Run this command As Administrator).

choco pin add -n vlc

Example Output:

vlc v3.0.18 pinned.

After running choco pin add, you should see a confirmation message indicating that the package and version have been successfully pinned.

choco pin list: View Currently Pinned Packages

This subcommand shows you which packages are currently pinned and the specific versions that are locked.

Syntax:

choco pin list

Explanation:

Running this command displays a list of all packages that you have previously pinned using choco pin add. It includes the Package ID and the exact version that is pinned.

Example:

choco pin list

Example Output:

googlechrome|120.0.6099.71
vlc|3.0.18
2 pins listed.

This list is essential for keeping track of which packages are excluded from standard upgrades. It helps you manage your software version control strategy.</

choco pin remove: Unpin a Package

When you no longer need a package to be pinned, you use the choco pin remove subcommand to take it off the pinned list.

Syntax:

choco pin remove -n <packageID> [--version <version>]

Explanation:

Use -n or --name followed by the Package ID. If you omit the --version option, Chocolatey will remove all pins associated with that Package ID, regardless of the version. If you have pinned multiple versions of the same package (a less common scenario), you would use --version to unpin a specific one.

Example: Unpin googlechrome specifically at version 120.0.6099.71 (Run this command As Administrator).

choco pin remove -n googlechrome --version 120.0.6099.71

Example Output:

googlechrome v120.0.6099.71 unpinned.

Example: Unpin *any* version of vlc that is currently pinned (Run this command As Administrator).

choco pin remove -n vlc

Example Output:

vlc unpinned.

A confirmation message will indicate that the pin has been successfully removed.

choco pin outdated: See Pinned Packages with Newer Versions

This subcommand is helpful for reviewing your pinned packages and seeing which ones have newer versions available. This doesn’t require Administrator privileges.

Syntax:

choco pin outdated

Explanation:

This command lists the packages that are currently pinned and shows the latest available version from your configured sources. It’s a great way to see what updates you are currently skipping due to pinning, allowing you to plan for future testing and potential unpinning/upgrading.

Example:

choco pin outdated

Example Output:

googlechrome 120.0.6099.71 [Upgradable to 121.0.6167.85]
vlc 3.0.18 [Upgradable to 3.0.19]
2 pinned packages outdated.

Demonstrating the Effect of Pinning

Let’s see how pinning affects the update process. Imagine you have googlechrome installed at version 120.0.6099.71 and a newer version 121.0.6167.85 is available. Let’s also assume you have another package, say notepadplusplus, which also has an update available.

Before pinning, running choco outdated would show both packages:

choco outdated

Example Output (before pinning):

googlechrome 120.0.6099.71 [Upgradable to 121.0.6167.85]
notepadplusplus 8.5.8 [Upgradable to 8.6.1]
2 packages are outdated.

Now, let’s pin googlechrome at 120.0.6099.71 (As Administrator):

choco pin add -n googlechrome --version 120.0.6099.71

Run choco outdated again:

choco outdated

Example Output (after pinning googlechrome):

notepadplusplus 8.5.8 [Upgradable to 8.6.1]
1 packages are outdated.

Notice that googlechrome no longer appears in the standard outdated list. It is now excluded from the upgrade process.

Finally, let’s run choco upgrade all (As Administrator):

choco upgrade all

Example Output (showing googlechrome being skipped):

Chocolatey v2.1.0
Upgrading the following packages:
notepadplusplus
By upgrading, you accept licenses for packages. . .
notepadplusplus v8.6.1 is being installed. . .
. . .
googlechrome v120.0.6099.71 is pinned. Skipping.
notepadplusplus has been upgraded to v8.6.1.

Upgraded: 1
Pinned: 1
Skipped: 0
Failed: 0

As you can see, notepadplusplus was upgraded, but googlechrome was explicitly identified as pinned and skipped, demonstrating the effectiveness of the Chocolatey pin package version command.

Considerations and Best Practices for Pinning

While pinning is a valuable tool, it should be used thoughtfully:

– Pin with Caution: Pinning prevents updates, including security patches and bug fixes. Only pin packages when absolutely necessary for stability or compatibility reasons.

– Document Your Pins: Keep a record of which packages are pinned, why they are pinned, and to which version. This documentation is crucial for maintenance and troubleshooting, especially in team environments.

– Regularly Review Pins: Use choco pin outdated periodically to see what updates you are missing. Plan for testing and upgrading pinned packages when it is safe to do so. Don’t let pins become permanent.

– Dependencies: Remember that pinning a package does not automatically pin its dependencies. If a dependency update could negatively impact your pinned package, you might need to consider pinning dependencies as well, which adds complexity.

Pinning vs. Version Ranges in Scripts/Packages

It’s worth noting the difference between using choco pin and specifying version ranges within Chocolatey package definition files (`.nuspec`).

Pinning, using the choco pin command, is a client-side configuration. It tells *your* Chocolatey installation to ignore a specific installed package during the upgrade process. It’s about controlling updates on a particular machine or set of machines.

Specifying version ranges in a `.nuspec` file (for package dependencies) is a package definition. It tells Chocolatey which versions of *other* packages are compatible dependencies for the package being installed. This is about defining requirements during installation, not preventing upgrades of already installed main packages.

Conclusion

The choco pin command is a powerful feature for intermediate and advanced Chocolatey users, particularly those responsible for maintaining stable software environments or dealing with specific compatibility requirements. By allowing you to selectively prevent automatic updates, it gives you precise control over your installed software versions.

While the convenience of choco upgrade all is a major benefit of Chocolatey, understanding and utilizing Chocolatey pin package version ensures that you can balance the desire for current software with the critical need for stability and compatibility when necessary. Use pinning judiciously, document your choices, and review your pinned packages regularly to maintain a healthy and controlled software ecosystem.

For the most authoritative and up-to-date information on the choco pin command, refer to the official Chocolatey documentation.