Chocolatey Cleanup

What This Script Does

The cleanup-chocolatey.ps1 script performs a comprehensive cleanup of your Chocolatey installation, removing accumulated debris that builds up over time as packages are installed, updated, and removed. Over weeks and months of regular Chocolatey use, old package versions, cached installer downloads, orphaned dependencies, and temporary files can consume significant disk space. This script targets all of these categories of waste and reclaims that space in a single automated operation, typically recovering between 500 megabytes and 2 gigabytes of disk space depending on how many packages you have installed and how long it has been since the last cleanup.

The most significant source of wasted space in a Chocolatey installation comes from old package versions. When Chocolatey updates a package, it does not automatically remove the previous version by default. This behavior is intentional because it allows users to roll back to a previous version if an update causes problems. However, after an update has been running successfully for a while, the old version serves no purpose and simply consumes disk space. The cleanup script identifies all packages that have older versions retained alongside the current version and removes those outdated copies. This process is safe because Chocolatey tracks which version is currently active, and the script only removes versions that are explicitly marked as superseded.

Cached package downloads represent another substantial source of disk usage. Every time Chocolatey installs or updates a package, it downloads the installer or package file to a local cache directory. These cached files are kept so that packages can be reinstalled without re-downloading them, which is useful in environments with limited or unreliable internet connectivity. However, for most users, these cached files are never accessed again after the initial installation. The cleanup script clears this cache entirely, freeing up the space consumed by what are effectively duplicate copies of software you have already installed. If you ever need to reinstall a package, Chocolatey will simply re-download it from the repository.

Orphaned dependencies are packages that were originally installed as dependencies of another package but are no longer needed because the parent package has been removed. For example, if you install a package that depends on a specific version of the Visual C++ runtime, and then later uninstall that package, the Visual C++ runtime may remain installed even though nothing else requires it. The cleanup script identifies these orphaned dependencies by analyzing the dependency graph of all installed packages and flagging any that are not directly installed or required by any other installed package. It then presents a summary of these orphaned packages in the log output. Note that the script takes a conservative approach here and logs orphaned dependencies for review rather than automatically removing them, since some packages may have been intentionally installed even though they appear as orphans in the dependency analysis.

Temporary files generated during package installation and update operations are the fourth category of cleanup targets. Chocolatey creates temporary directories during package operations to stage files, extract archives, and run installation scripts. While these temporary directories are normally cleaned up after each operation, failures or interruptions during installation can leave behind temporary directories that never get removed. The cleanup script scans the Chocolatey temporary directory for any leftover artifacts and removes them. These remnants are typically small individually, but on systems that have experienced multiple interrupted installations, they can accumulate to a noticeable amount.

The script operates with a clear before-and-after measurement approach. At the start of execution, it calculates the total disk space consumed by the Chocolatey installation directory and its caches. After performing all cleanup operations, it measures the same directories again and reports the total amount of space reclaimed. This measurement gives you concrete, quantifiable feedback on the value of running the cleanup. The disk space figures are reported in both the console output and the log file, making it easy to track cleanup effectiveness over time.

After completing all cleanup operations, the script automatically runs the choco doctor health check command. This step verifies that the cleanup process did not inadvertently affect any active packages or configurations. The health check validates the Chocolatey installation integrity, checks that all currently installed packages are in a consistent state, and reports any issues that need attention. Running the health check after cleanup provides confidence that the system is in a clean, healthy state when the script completes.

The script is designed to be completely idempotent and safe to run multiple times. If you run the cleanup script on a system that was recently cleaned, it will simply find nothing to remove and report that the Chocolatey installation is already in a clean state. There is no risk of the script removing files that should not be deleted, removing packages that are still in use, or corrupting the Chocolatey installation in any way. This safety characteristic makes it suitable for inclusion in scheduled maintenance routines where it might run weekly or monthly regardless of whether cleanup is actually needed.

Error handling in the cleanup script follows the same resilient pattern used throughout the toolkit. Each cleanup operation is performed independently, so a failure in one area does not prevent the other areas from being cleaned. For example, if a file lock prevents the removal of a particular cached package, the script logs the issue and continues cleaning other cached packages and performing the remaining cleanup operations. The final summary report indicates which operations succeeded and which encountered issues, giving you a complete picture of what was accomplished.

All activity is logged to %USERPROFILE%\Logs\ChocolateyCleanup.log with detailed timestamps and descriptions of every action taken. The log includes the list of old package versions removed, the number and total size of cached files deleted, any orphaned dependencies identified, the count of temporary files cleaned up, the disk space before and after measurements, and the results of the post-cleanup health check. This log serves as both a troubleshooting resource and an audit trail of maintenance activities.

For optimal results, consider running this script on a regular schedule. Monthly cleanup is sufficient for most users, but systems with many frequently-updated packages may benefit from weekly cleanup. The setup-scheduled-tasks.ps1 script can configure a Windows Scheduled Task to run the cleanup automatically, ensuring your Chocolatey installation stays lean without requiring manual intervention.

Usage

Open an elevated PowerShell window and navigate to the script directory.

# Run the cleanup script
.\cleanup-chocolatey.ps1

The script will output progress information as it works through each cleanup phase:

# Example output
[2026-02-20 10:30:15] Starting Chocolatey cleanup...
[2026-02-20 10:30:15] Disk usage before cleanup: 4.2 GB
[2026-02-20 10:30:16] Removing old package versions...
[2026-02-20 10:30:22] Removed 14 old package versions
[2026-02-20 10:30:22] Clearing package cache...
[2026-02-20 10:30:25] Cleared 856 MB of cached downloads
[2026-02-20 10:30:25] Cleaning temporary files...
[2026-02-20 10:30:26] Removed 12 temporary artifacts
[2026-02-20 10:30:26] Running health check...
[2026-02-20 10:30:30] Health check passed
[2026-02-20 10:30:30] Disk usage after cleanup: 2.8 GB
[2026-02-20 10:30:30] Total space reclaimed: 1.4 GB

What Gets Changed

• Old package versions — Superseded versions of installed packages are removed from the Chocolatey lib directory.
• Package cache — Downloaded installer files in the Chocolatey cache directory are deleted.
• Temporary files — Leftover temporary directories from interrupted installations are removed.
• Orphan detection — Orphaned dependencies are identified and logged for manual review.
• Health check — A post-cleanup choco doctor health check validates installation integrity.
• Log file — Creates or appends to %USERPROFILE%\Logs\ChocolateyCleanup.log.

Related Scripts