Backup & Restore

What This Script Does

The backup-packages.ps1 script provides a complete backup and restore solution for your Chocolatey package inventory. It addresses one of the most common challenges in Windows system management: reproducing your exact software environment on a new machine or recovering it after a system reinstallation. Rather than trying to remember every application you had installed and manually reinstalling each one, this script captures your entire package list in a structured JSON file that can be used to restore all packages in a single operation.

The script operates in two distinct modes controlled by the -Action parameter: Backup mode and Restore mode. In Backup mode, the script queries Chocolatey for a complete list of all installed packages, including their current version numbers, and exports this information to a JSON file. In Restore mode, the script reads a previously created backup file and installs every package listed in it, effectively recreating the software environment from the backup. This dual-mode design means a single script handles the entire backup-restore lifecycle.

When running in Backup mode, the script collects significantly more information than just package names. For each installed package, the backup file records the package identifier (the name used to install it via Chocolatey), the currently installed version number, whether the package is pinned (protected from automatic updates), and the date the backup was created. This metadata is important for several reasons. The version numbers allow you to restore packages at the exact versions you had installed rather than whatever the latest version happens to be at restore time, which is particularly valuable if you need to maintain specific versions for compatibility reasons. The pinned status ensures that any packages you had intentionally locked to a specific version remain locked after restoration.

The JSON format was chosen for the backup file because it is human-readable, easily editable, and supported by virtually every programming language and tool. You can open a backup file in any text editor to review its contents, manually add or remove packages before restoring, or write your own scripts that consume the backup data. The JSON structure also makes it straightforward to compare two backup files to see what has changed between backups, which is useful for tracking software changes over time or auditing differences between machines.

By default, backup files are stored in the %USERPROFILE%\Documents\ChocolateyBackups\ directory with a filename that includes the date and time of the backup, such as ChocolateyBackup_2026-02-20_143022.json. This naming convention makes it easy to identify when each backup was created and to maintain multiple backup files as a history of your package inventory at different points in time. The backup directory is created automatically if it does not exist. You can override the default location by specifying a custom path with the -BackupFile parameter, which is useful if you want to save backups to a network share, cloud-synced folder, or external drive.

The Restore mode is where the real power of this script becomes apparent. When you point it at a backup file, it reads the package list and begins installing each package using Chocolatey. The restore process handles several edge cases intelligently. If a package in the backup is already installed on the target machine, the script skips it rather than attempting a redundant installation. If a specific version recorded in the backup is no longer available in the Chocolatey repository (which can happen with older packages), the script falls back to installing the latest available version and logs the version discrepancy. If a package fails to install, the error is logged and the script continues with the remaining packages, ensuring that one problematic package does not block the restoration of your entire software library.

The migration use case is perhaps the most compelling scenario for this script. When setting up a new computer, the typical workflow involves hours of downloading and installing applications, configuring each one, and trying to remember everything you had on your old machine. With this backup and restore system, the workflow becomes much simpler: run a backup on your old machine, transfer the JSON file to your new machine (via USB drive, email, cloud storage, or any other method), install Chocolatey on the new machine using install-chocolatey.ps1, and then run a restore. The entire software environment from your old machine will be reproduced on the new one, typically in a fraction of the time it would take to reinstall everything manually.

Disaster recovery is another important use case. If your system drive fails or becomes corrupted, having a recent package backup means you can rebuild your software environment quickly after reinstalling Windows. For this reason, it is recommended to store backup files in a location that is separate from your system drive, such as an external drive, network share, or cloud storage service. Some users configure a scheduled task to create weekly or monthly backups automatically, ensuring they always have a recent package list available for recovery.

The script also serves as a documentation tool. Even if you never need to restore from a backup, having a JSON file that lists every Chocolatey-managed application on your system is valuable for inventory purposes. IT departments can use these backup files to document the standard software configuration for different roles, compare the software installed on different machines, or create a baseline configuration that new machines should be set up with. The structured JSON format makes it easy to process these files programmatically for reporting and analysis.

Error handling in the backup process is straightforward since the operation is essentially read-only: querying the list of installed packages and writing a JSON file. The restore process has more robust error handling, with per-package logging of success and failure states, a summary report at the end showing how many packages were restored, how many were already present, and how many failed. The script exits with a success code when all packages are restored and a specific error code when one or more packages could not be installed, making it suitable for use in automated workflows where the exit code needs to be checked.

All operations are logged to %USERPROFILE%\Logs\ChocolateyBackup.log, including the full list of packages included in each backup, the path where the backup file was saved, and detailed per-package results during restore operations. The log file provides a complete audit trail of all backup and restore activities, which is useful for troubleshooting and for verifying that backup and restore operations completed successfully.

Usage

Creating a Backup

# Create a backup with the default filename and location
.\backup-packages.ps1 -Action Backup

# Create a backup at a custom location
.\backup-packages.ps1 -Action Backup -BackupFile "D:\Backups\my-packages.json"

Restoring from a Backup

# Restore from the most recent backup (requires Administrator)
.\backup-packages.ps1 -Action Restore

# Restore from a specific backup file
.\backup-packages.ps1 -Action Restore -BackupFile "D:\Backups\my-packages.json"

Parameters

Parameter	Type	Required	Description
-Action	String	Yes	The operation to perform: Backup or Restore.
-BackupFile	String	No	Custom path for the backup file. Defaults to %USERPROFILE%\Documents\ChocolateyBackups\ with a timestamped filename.

What Gets Changed

• Backup mode — Creates a JSON file containing the list of all installed Chocolatey packages and their versions. No system changes.
• Restore mode — Installs all packages listed in the backup file via Chocolatey, modifying program files and system PATH as needed.
• Backup directory — Creates %USERPROFILE%\Documents\ChocolateyBackups\ if it does not exist.
• Log file — Creates or appends to %USERPROFILE%\Logs\ChocolateyBackup.log.

Related Scripts