Recommendations on Installing & Upgrading Chocolatey Licensed Clients

Our goal in the recent releases of Chocolatey CLI and Chocolatey Licensed Extension has been to make it easier for customers upgrading the Chocolatey licensed clients. Here we look to review some of the changes we have made and the recommendations for a compatible and supported configuration.

The Chocolatey licensed clients we will be focusing on are:

• Chocolatey CLI
• Chocolatey Licensed Extension
• Chocolatey GUI
• Chocolatey GUI Licensed Extension
• Chocolatey Agent

Chocolatey CLI uses package dependencies that ensure specific packages and versions are installed prior to installing the package you requested. For Chocolatey products we can ensure that all the required package versions are installed. For example, if you were to install chocolateygui.extension then it would make sure that the following tree of packages, with these package versions as a minimum, are installed:

Package Name / Dependency	chocolatey	chocolatey.extension	chocolateygui
chocolatey v1.1.0
chocolatey.extension v4.1.0	v1.0.0
chocolatey-agent v1.0.0		v4.0.0
chocolateygui v1.0.0	v1.0.0
chocolateygui.extension v1.0.0		v4.0.0	v1.0.0

NOTE

Newer package versions may be available at the time of installation, and Chocolatey will pick the highest available that matches the defined dependency range.

While Chocolatey CLI can ensure that direct package dependencies are satisfied, it cannot ensure that indirect package dependencies are satisfied. For example, if you currently have chocolateygui version 0.18.1 installed along with chocolateygui.extension version 0.2.1, and you first upgrade to chocolateygui version 0.19.0, you will see errors if you attempt to run Chocolatey GUI as the chocolateygui.extension package also needs to be updated.

Recommended Install / Upgrade Order

Based on direct package dependencies, the recommended order to install or upgrade is:

• chocolateygui.extension
• chocolateygui
• chocolatey-agent
• chocolatey.extension
• chocolatey

This will ensure that all dependencies, both direct and indirect, are installed.

Telling You When Incompatible Versions Detected

With the release of Chocolatey CLI version 1.1.0 and Chocolatey Licensed Extension version 4.1.0, we tell you when you may be getting into an incompatible and unsupported configuration.

If you have a Chocolatey Perpetual License you have access to use the versions of Chocolatey licensed products while your Maintenance and Support agreement is active. This may mean that you do not have the latest version of the Chocolatey Licensed Extension. While we recommend that you always use compatible versions of Chocolatey licensed products, as we highlighted above, as a Perpetual License customer this may not be possible.

Where you have a version of Chocolatey Licensed Extension installed that may not be compatible with the version of Chocolatey CLI you are upgrading to, we have added a warning:

WARNING

You are installing a version of Chocolatey that may not be compatible with the currently installed version of the chocolatey.extension package. Running Chocolatey with the current version of the chocolatey.extension package is an unsupported configuration. See https://ch0.co/compatibility for more information.

If you are also modifying the chocolatey.extension package, you can ignore this warning.

While in this incompatible and unsupported configuration we have added a warning before and after any Chocolatey CLI command is run to ensure that it’s clear that you may be in an incompatible and unsupported configuration:

WARNING

You are running a version of Chocolatey that may not be compatible with the currently installed version of the chocolatey.extension package. Running Chocolatey with the current version of the chocolatey.extension package is an unsupported configuration.

See https://ch0.co/compatibility for more information.

If you are in the process of modifying the chocolatey.extension package, you can ignore this warning.

Additionally, you can ignore these warnings by either setting the DisableCompatibilityChecks feature:

choco feature enable --name="'disableCompatibilityChecks'"

Or by passing the --skip-compatibility-checks option when executing a command.

If you know what you are doing, you can disable these warnings by adding the --skip-compatibility-checks to any Chocolatey CLI command or by enabling the feature disableCompatibilityChecks using choco feature enable --name="'disableCompatibilityChecks'".

For Perpetual License Customers, the options to ensure you are in a compatible and supported configuration are:

1. Renew the Maintenance and Support, upgrade the Chocolatey Licensed Extension to the latest version and then upgrade Chocolatey CLI. Reach out to the Sales Team for more information.
2. Stay with the Chocolatey Licensed Extension and Chocolatey CLI versions you use and that you know are compatible. We would recommend you pin to those versions so that you do not accidentally upgrade them in future.

Recommended Way To Upgrade All Packages

When upgrading all packages using the choco upgrade all command either directly, through a scheduled task or using a package such as choco-upgrade-all-at-startup there are some considerations that need to be made. The order in which packages are upgraded in can potentially cause you to get into an incompatible and unsupported configuration. To avoid this situation, upgrade the Chocolatey licensed clients in the recommended order above, before running any choco upgrade all.

To help with this we have added a new feature excludeChocolateyPackagesDuringUpgradeAll:

NOTE

:choco-info: NOTE

excludeChocolateyPackagesDuringUpgradeAll - Exclude Chocolatey Packages During Upgrade All - When enabled, all official Chocolatey packages will be added to the comma-separated list of package names that should not be upgraded when upgrading ‘all’. Any packages specified in the ‘upgradeAllExceptions’ configuration setting will still be respected. Licensed editions only (version 4.1.0+).

When this feature is enabled it will prevent all installed Chocolatey official packages (which includes those we talk about here) from being upgraded as part of a choco upgrade all command. This feature is disabled by default, but we recommend you enable it using choco feature enable --name="'disableCompatibilityChecks'" and then upgrade the Chocolatey official packages in the order we recommended above. This feature may be enabled by default in a future release.

Release Notes

For more information on the releases, please see the Chocolatey CLI release notes and Chocolatey Licensed Extension release notes.

Learn More

• Check out the documentation.
• Learn about other features available in Chocolatey for Business.
• Contact us to find out more and set up your evaluation of Chocolatey for Business today.