What This Script Does
The health-check.ps1 script serves as your system's diagnostic dashboard for Chocolatey, providing a thorough examination of the package manager installation, its configuration, the state of all managed packages, and the underlying system resources that Chocolatey depends on. Think of it as a comprehensive physical examination for your Windows software management infrastructure. The script gathers data from multiple sources, analyzes it against known best practices and common problem patterns, and presents a clear, structured report with actionable recommendations for anything that needs attention.
The diagnostic process begins with the most fundamental check: verifying that Chocolatey is actually installed and accessible. The script confirms that the choco command is available in the system PATH, that the Chocolatey installation directory exists at its expected location, and that the installed version of Chocolatey is reasonably current. If Chocolatey is not installed or the installation appears damaged, the script reports this immediately and directs you to the install-chocolatey.ps1 script for a fresh installation. This initial check prevents the more detailed diagnostics from producing misleading results based on a fundamentally broken installation.
The configuration analysis phase examines the settings and features that control how Chocolatey operates. The script checks whether the execution policy is set appropriately for running Chocolatey scripts, whether global confirmation mode is enabled (which is required for automated scripts in this toolkit), and whether the Chocolatey source repositories are properly configured. It also verifies that the Chocolatey binary directory is correctly listed in the system PATH and that there are no duplicate or conflicting PATH entries. Configuration issues are one of the most common causes of mysterious Chocolatey failures, and this diagnostic phase catches problems that might otherwise require hours of troubleshooting to identify.
The outdated packages check is one of the most immediately useful diagnostics. The script runs choco outdated to query the Chocolatey Community Repository for newer versions of all installed packages. The results are presented in a formatted table showing the package name, the currently installed version, the latest available version, and whether the package is pinned (protected from automatic updates). This information tells you at a glance how current your software is and which packages need attention. Packages that are significantly behind their latest version are flagged with higher priority, as older versions may have known security vulnerabilities or bugs that have been fixed in newer releases.
Disk usage analysis provides visibility into how much storage space your Chocolatey installation is consuming. The script calculates the total size of the Chocolatey installation directory, the package cache, and the lib directory where installed packages are stored. It breaks these figures down by category so you can see where the space is being used. If the cache has grown large enough to warrant cleanup, the script recommends running cleanup-chocolatey.ps1. The disk usage analysis also checks the available free space on the system drive and warns if it has fallen below a recommended threshold, since low disk space can cause package installations and updates to fail.
System requirements verification ensures that your Windows environment meets all the prerequisites for running Chocolatey and the scripts in this toolkit. The script checks the Windows version and build number to confirm you are running Windows 10 or Windows 11, verifies that PowerShell 5.1 or later is available, and checks that the .NET Framework version meets Chocolatey's minimum requirements. It also verifies that the current user has Administrator privileges, which are required for most Chocolatey operations, and checks whether the Windows Task Scheduler service is running, which is needed for automated maintenance tasks.
The built-in choco doctor command is executed as part of the diagnostic suite, providing Chocolatey's own internal health assessment. This command checks for common installation issues, verifies that the NuGet infrastructure is functioning correctly, and validates that Chocolatey's configuration file is well-formed and contains valid settings. The doctor command can detect issues that are specific to Chocolatey's internal state and would not be caught by the other diagnostic checks, making it a valuable complement to the script's own analysis.
One of the most valuable aspects of this script is its recommendation engine. Rather than simply presenting raw data, the script interprets the diagnostic results and generates specific, actionable recommendations. If it finds outdated packages, it recommends running the auto-update script. If disk usage is high, it recommends running the cleanup script. If configuration issues are detected, it explains exactly what settings need to be changed and provides the commands to make those changes. These recommendations transform raw diagnostic data into a clear action plan, making it easy for users of all experience levels to maintain their Chocolatey installation.
The script is designed to run safely in a read-only manner. It does not modify any settings, install or remove any packages, or change any system configuration. Its sole purpose is to gather information and report findings. This makes it perfectly safe to run at any time, even on production systems or machines managed by others. The read-only nature also means that the script can be run without Administrator privileges for most checks, though some diagnostics (particularly the choco doctor command and certain system information queries) produce more complete results when run elevated.
All diagnostic results are output to the console in a formatted, color-coded display that makes it easy to distinguish between passed checks (green), warnings (yellow), and failures (red). The same information is simultaneously written to %USERPROFILE%\Logs\ChocolateyHealthCheck.log in a structured text format suitable for archival and comparison over time. By running the health check periodically and comparing log files, you can track the health of your Chocolatey installation over time and identify trends such as gradually increasing disk usage or a growing number of outdated packages.
The health check script is recommended as a regular maintenance practice. Running it weekly or monthly provides early warning of developing issues before they become problems. It is also an excellent first step when troubleshooting any Chocolatey-related issue, as the comprehensive diagnostics often reveal the root cause immediately. Many users include the health check as part of their morning routine when setting up for a development session, taking 30 seconds to verify that their tools are in good shape before beginning work.
Usage
The health check can be run with or without Administrator privileges. Elevated mode provides more complete results.
# Run the health check
.\health-check.ps1
# For the most complete results, run as Administrator
# Right-click PowerShell > Run as Administrator
.\health-check.ps1The output is organized into clearly labeled sections:
# Example output sections
====================================
CHOCOLATEY HEALTH CHECK REPORT
====================================
[PASS] Chocolatey Installation
Version: 2.4.1
Path: C:\ProgramData\chocolatey
[PASS] Configuration
Global Confirmation: Enabled
Execution Policy: RemoteSigned
[WARN] Outdated Packages (5 of 24 packages)
googlechrome 131.0.6778 > 132.0.6834
firefox 133.0 > 134.0.1
...
[PASS] Disk Usage
Installation: 2.1 GB
Cache: 340 MB
Free Space: 89 GB
[PASS] System Requirements
Windows 11 23H2
PowerShell 7.4.1
.NET Framework 4.8.1
Recommendations:
- Run auto-update-chocolatey.ps1 to update 5 outdated packages
- Consider running cleanup-chocolatey.ps1 to clear 340 MB of cacheWhat Gets Changed
- No system modifications — This script is read-only and does not modify any settings, packages, or files on your system.
- Log file — Creates or appends to
%USERPROFILE%\Logs\ChocolateyHealthCheck.logwith diagnostic results. - Console output — Displays a formatted health check report in the PowerShell window.