Getting Started

Requirements

Before you begin, make sure your system meets the following requirements. These PowerShell scripts are designed to work on modern Windows systems and require a few basic prerequisites to function properly. If you are unsure about any of these, read through the notes below each item for guidance.

• Windows 10 (version 1809 or later) or Windows 11 — These scripts are designed and tested on modern Windows releases. Earlier versions of Windows may lack the PowerShell features and system APIs that the scripts depend on. You can check your Windows version by pressing Win + R, typing winver, and pressing Enter.
• PowerShell 5.1 or later (PowerShell 7+ recommended) — PowerShell 5.1 ships with Windows 10 and 11, so you likely already have it. However, PowerShell 7+ offers significantly faster execution, improved error handling, and modern language features that make the scripts more reliable. You can check your current version by opening PowerShell and running $PSVersionTable.PSVersion.
• Administrator privileges — Chocolatey installs software system-wide, which requires elevated permissions. You will need to run PowerShell as Administrator for most operations. If you are not an administrator on your machine, you will need someone with those rights to assist during setup.
• Active internet connection — A stable connection is required to download Chocolatey itself and all packages you choose to install. Wired or strong Wi-Fi connections are recommended, especially during the initial setup which may download several hundred megabytes of data.
• At least 10 GB free disk space — Chocolatey, its package cache, and the applications you install will need room on your drive. The actual space required depends on how many applications you choose to install. You can check your available storage by opening File Explorer, right-clicking your C: drive, and selecting Properties.

If your system does not meet one or more of these requirements, the scripts include pre-flight checks that will detect the issue and let you know what needs to be resolved before continuing.

Step 1 — Download the Scripts

There are two ways to get the scripts onto your Windows machine. Choose the option that best fits your workflow. If you are comfortable with Git and want to receive updates easily, cloning is the way to go. If you just want to grab the files quickly and do not plan to track upstream changes, downloading the ZIP is perfectly fine.

Option A: Clone with Git

Cloning creates a local copy of the repository that is linked to the original on GitHub. This makes it easy to pull down updates later with a single git pull command, and also lets you contribute back if you find improvements to share.

# Open PowerShell and clone the repository
git clone https://github.com/DJCastle/chocolateyScripts.git

# Move into the project folder
cd chocolateyScripts

If you do not have Git installed yet, you can install it later using Chocolatey itself (choco install git -y), or download it manually from git-scm.com. For now, Option B below does not require Git.

Option B: Download ZIP

If you prefer not to use Git, you can download the entire project as a ZIP file directly from GitHub. This is a quick option if you want to get started right away without setting up Git first.

1. Visit the GitHub repository in your browser.
2. Click the green Code button and select Download ZIP.
3. Extract the ZIP file to a convenient location (such as C:\Users\YourName\chocolateyScripts).
4. Open PowerShell and navigate to the extracted folder.

Alternatively, you can download and extract using PowerShell directly:

# Download the latest version as a ZIP file
Invoke-WebRequest -Uri "https://github.com/DJCastle/chocolateyScripts/archive/refs/heads/main.zip" -OutFile "$env:TEMP\chocolateyScripts.zip"

# Extract to your home directory
Expand-Archive -Path "$env:TEMP\chocolateyScripts.zip" -DestinationPath "$env:USERPROFILE"

# Move into the project folder
cd "$env:USERPROFILE\chocolateyScripts-main"

Step 2 — Set Execution Policy

By default, Windows does not allow PowerShell scripts to run. This is a security measure that prevents scripts from running unintentionally. Before you can execute any of the Chocolatey Scripts, you need to adjust the execution policy to allow locally-created scripts to run while still requiring downloaded scripts to be signed.

Open PowerShell as Administrator (right-click the PowerShell icon and select "Run as Administrator") and run the following command:

# Allow local scripts to run (one-time setup)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

The RemoteSigned policy is a balanced security setting. It allows scripts created on your local machine to run freely, while scripts downloaded from the internet must have a valid digital signature. This is the recommended setting for most users and is the same policy that Microsoft suggests for development environments.

You can verify the current execution policy at any time by running:

# Check the current execution policy
Get-ExecutionPolicy

If you see RemoteSigned in the output, you are ready to proceed. If you see Restricted, the command above did not take effect and you may need to run PowerShell as Administrator again. Some organizations enforce execution policies through Group Policy, in which case you may need to contact your IT department.

Step 3 — Install Chocolatey

With the execution policy configured, you are ready to install Chocolatey itself. The installation script handles everything automatically, including downloading Chocolatey, configuring environment variables, and running initial health checks to verify the installation succeeded.

Make sure you are in the project directory and running PowerShell as Administrator, then execute:

# Install the Chocolatey package manager
.\install-chocolatey.ps1

What This Script Does

The installation script performs the following operations in order:

• Downloads and installs Chocolatey from the official source at chocolatey.org. If Chocolatey is already installed, the script detects this and skips the installation step entirely, making it safe to run multiple times.
• Configures environment variables so that the choco command is available in all future PowerShell and Command Prompt sessions without needing to restart your computer.
• Enables global confirmation by running choco feature enable -n allowGlobalConfirmation. This reduces interactive prompts during package installations, which is essential for automated scripts.
• Runs health checks using choco doctor to verify that the installation is healthy and all components are functioning correctly.
• Creates installation logs in %USERPROFILE%\Logs\ with a timestamped record of every operation performed.

Expected Output

During a successful installation, you will see green success messages showing the installation progress, the Chocolatey version number, and the configuration status. If anything goes wrong, error messages will appear in red with clear descriptions of what failed and how to fix it.

After the script completes, you can verify the installation by running:

# Verify Chocolatey is installed and check its version
choco --version

If you see a version number (for example, 2.4.1), Chocolatey is installed and working correctly. If you get a "command not found" error, try closing and reopening PowerShell, or run refreshenv to reload environment variables in the current session.

Step 4 — Install Essential Applications

With Chocolatey installed, you can now use the essential apps script to install a curated set of applications that most Windows users need. This script batch-installs everything in one pass, saving you the time and effort of visiting multiple websites, downloading individual installers, and clicking through setup wizards for each application.

# Install the curated set of essential Windows applications
.\install-essential-apps.ps1

Applications Installed

The script installs the following categories of applications by default:

• Browsers — Google Chrome, Mozilla Firefox, Microsoft Edge (if not already present)
• Development Tools — Visual Studio Code, Notepad++, Git, PowerShell 7+
• Utilities — 7-Zip, VLC Media Player, Windows Terminal
• Communication — Discord
• Gaming — Steam

Each application is installed using Chocolatey's verified community packages, which means you get the official versions from trusted sources with automatic checksum verification.

Customizing the Application List

You do not have to install every application in the default list. The script uses a $apps array that you can edit to add or remove applications before running it. Open the script in any text editor to customize:

# View or edit the application list
notepad .\install-essential-apps.ps1

# Or use PowerShell to view the current list
Get-Content .\install-essential-apps.ps1 | Select-String "\$apps"

To find the correct package name for an application you want to add, search the Chocolatey package repository or use the command line:

# Search for a package by name
choco search firefox

# Get detailed information about a specific package
choco info googlechrome

Step 5 — Run Health Check

After installing Chocolatey and your applications, it is important to run a comprehensive health check to verify that everything is working correctly. The health check script examines your entire Chocolatey installation and reports any issues that need attention.

# Run the comprehensive health check
.\health-check.ps1

What It Checks

The health check script performs a thorough examination of your system:

• Chocolatey installation status — Verifies that Chocolatey is installed, accessible from the command line, and running the latest version.
• System requirements — Confirms that your Windows version, PowerShell version, and available disk space all meet the minimum requirements.
• Outdated packages — Lists all installed packages that have newer versions available, along with the current and latest version numbers.
• Disk usage — Reports how much disk space is being used by Chocolatey's package cache and installed applications, and warns if free space is running low.
• Configuration issues — Checks for common configuration problems such as missing config files, invalid settings, or conflicting options.
• Scheduled tasks — Reports on any Chocolatey-related scheduled tasks, their status, and when they last ran.

The health check uses color-coded output to make results easy to scan: green for items that pass, yellow for warnings that deserve attention, and red for errors that need to be fixed. A summary at the end gives you a quick overview of your system's overall health.

Configuration

The config.json file centralizes all script settings in one place. Rather than editing individual scripts to change behavior, you modify this single configuration file. An example configuration ships with the project so you can see all available options and their default values.

Start by copying the example configuration to create your own personal config file:

# Create your config from the example template
Copy-Item config.example.json config.json

# Open the config file in Notepad for editing
notepad config.json

Here are the key settings you will want to review and customize:

Setting	What It Does
wifiNetwork	Only run auto-updates when connected to this specific Wi-Fi network. Set this to your home or office network name to prevent large downloads on metered or slow connections. The name must match your SSID exactly, including capitalization.
emailAddress	Where to send update reports. After each automatic update, you will receive a summary of what was updated, what failed, and any action items. Requires SMTP configuration (see below).
smtpServer / smtpPort	SMTP server settings for email notifications. For Gmail, use smtp.gmail.com on port 587. You will need to create an App Password for authentication.
notifications	Controls which types of notifications are sent. You can independently enable or disable email notifications, toast notifications, and filter by event type (success, error, warning).
backupSettings	Configure automatic backups before updates. Set the backup directory path, enable or disable auto-backup, and control how many backup files to keep before old ones are rotated out.
maxRetries	Number of times to retry a failed operation (such as a network download) before giving up. The default of 3 works well for most connections.

The example config file includes sensible defaults, so you do not need to configure everything right away. The most important setting to customize is wifiNetwork if you plan to use automatic updates.

Creating an Initial Backup

Before making any further changes, it is a good idea to create a backup of your current package configuration. This gives you a restore point if you ever need to set up a new machine or recover from a problem.

# Create a backup of all installed packages
.\backup-packages.ps1 -Action Backup

Your backup will be saved as a JSON file at:
%USERPROFILE%\Documents\ChocolateyBackups\chocolatey-backup-YYYY-MM-DD_HHMMSS.json

This file contains a complete list of every Chocolatey package installed on your system along with version numbers. You can use it later to restore your exact package configuration on a fresh Windows installation.

Running Scripts

With everything installed and configured, here is how to use the scripts for ongoing maintenance of your Windows system. Each script is designed to be run independently, so you can use whichever ones fit your workflow.

Manual Updates

Keep all your installed packages up to date with the latest versions:

# Update all Chocolatey packages
.\auto-update-chocolatey.ps1

The update script is smart about when and how it runs. Before starting any downloads, it checks three conditions:

• WiFi network — Connected to the network specified in config.json (configurable, can be disabled)
• Power status — Plugged into AC power, not running on battery (important for laptops)
• Administrator privileges — Running with the elevated permissions Chocolatey needs

If all conditions are met, the script updates Chocolatey itself, upgrades all installed packages to their latest versions, runs cleanup to remove old package versions, sends notifications if configured, and logs all operations to the log directory.

Manual Cleanup

Over time, Chocolatey accumulates old package versions and cached files that take up disk space. The cleanup script removes these safely:

# Free up disk space by cleaning old packages and caches
.\cleanup-chocolatey.ps1

The cleanup script removes old package versions that are no longer needed, cached package download files, orphaned dependencies left behind by uninstalled packages, and temporary installation files. Typical disk space savings range from 500 MB to 2 GB depending on how many packages you have installed and how long it has been since your last cleanup.

Health Monitoring

Run the health check script periodically to catch issues early:

# Run a comprehensive system health check
.\health-check.ps1

Good times to run a health check include after installing new packages, when experiencing issues with installed applications, as part of monthly maintenance, and before running major updates.

Optional — Automation Setup

Once you have Chocolatey and your applications installed, you can set up automatic maintenance to keep everything current without manual intervention. The automation system uses Windows Task Scheduler to run updates and cleanup on a schedule you define.

# Launch the interactive automation setup wizard
.\setup-scheduled-tasks.ps1

The setup wizard walks you through creating scheduled tasks with an interactive menu. You have three main options:

1. Auto-Update Task

Schedules automatic package updates. You choose which days of the week to run (for example, Sunday and Wednesday) and the time of day (for example, 3:00 AM). The task only runs when conditions are met: connected to your specified WiFi network and plugged into power.

2. Cleanup Task

Schedules automatic disk space reclamation. Choose from daily, weekly, or monthly frequencies. Runs during off-peak hours to minimize any impact on system performance while keeping your disk tidy.

3. View and Manage Tasks

Review existing Chocolatey scheduled tasks, check when they last ran, see their next scheduled run time, and remove any tasks you no longer want.

Recommended Schedule

For most users, we recommend the following schedule:

Task	Schedule	Rationale
Auto-Update	Sunday and Wednesday at 3:00 AM	Twice-weekly updates ensure timely security patches without excessive network usage. Running at 3:00 AM avoids interference with work hours.
Cleanup	Monthly (first Sunday of the month)	Monthly cleanup prevents cache bloat without running so frequently that it wastes CPU cycles. Once a month is sufficient for most users.

You can verify that your scheduled tasks were created successfully using PowerShell:

# List all Chocolatey scheduled tasks
Get-ScheduledTask | Where-Object { $_.TaskName -like "*Chocolatey*" }

Logs

All scripts produce detailed logs that record every action taken, along with timestamps and status indicators. Logs are your best friend when troubleshooting — they contain a complete record of what happened, what succeeded, and what failed. Every log entry includes a severity level (INFO, WARNING, ERROR, SUCCESS) so you can quickly scan for issues.

Log files are stored in your user profile's Logs directory:

# List all Chocolatey Scripts log files
Get-ChildItem "$env:USERPROFILE\Logs\Chocolatey*.log"

# View the most recent log entries (last 50 lines)
Get-Content "$env:USERPROFILE\Logs\ChocolateyInstall.log" -Tail 50

# Search logs for errors across all log files
Get-ChildItem "$env:USERPROFILE\Logs\Chocolatey*.log" |
    ForEach-Object { Select-String "ERROR" $_ }

# View recent errors with context
Get-Content "$env:USERPROFILE\Logs\*.log" |
    Select-String "ERROR" |
    Select-Object -Last 20

If something goes wrong during a script run, the log file should be the first place you check. It will show you exactly which step failed and usually includes an error message from the underlying tool that explains why. Log entries include timestamps in the format [2026-02-06 14:30:15], making it easy to correlate events and understand the sequence of operations.

Tips for Success

Next Steps

Now that you are set up, here are some resources to help you go further:

• Safety & Best Practices — Understand the safety features built into these scripts and learn best practices for working with system automation on Windows.
• PowerShell Scripting Guide — Learn PowerShell scripting concepts by studying the real-world patterns used in these automation scripts.
• FAQ — Answers to common questions about installation, configuration, and troubleshooting.
• GitHub Repository — Browse the source code, report issues, and contribute improvements.
• Chocolatey Documentation — The official Chocolatey docs for in-depth reference on package management.
• Package Search — Browse thousands of available Chocolatey packages to expand your setup.

Recommended Workflow

Once everything is configured, here is the workflow that works best for most users:

# Weekly: Check for updates (or let the scheduled task handle it)
.\auto-update-chocolatey.ps1

# Monthly: Run health check and cleanup
.\health-check.ps1
.\cleanup-chocolatey.ps1

# Monthly: Create a backup of your package list
.\backup-packages.ps1 -Action Backup

# As needed: Install new packages
choco install package-name -y