Chocolatey · ArchWorks

Chocolatey is a machine-level, command-line package manager for Windows that automates software installation, upgrades, configuration, and removal.

Table of Contents#

Overview
Installation
Package Operations
Package Sources
Configuration
Version Pinning
Package Creation
Automated Installation Scripts
Proxy Configuration
Organizational Deployment
Chocolatey vs Winget
Troubleshooting
See Also
Sources

1. Overview#

Chocolatey wraps Windows installers (MSI, EXE, MSIX), zip archives, and scripts into a consistent package management interface. It uses NuGet infrastructure under the hood and provides a public community repository with thousands of packages, as well as support for private/internal package sources.

Key features:

Command-line management - install, upgrade, and remove software without manual intervention
Dependency resolution - automatically installs required dependencies
Multiple sources - use the community repository, internal feeds, or local folders
Version pinning - lock packages to specific versions to prevent unintended upgrades
Integration - works with PowerShell, SCCM, Ansible, Puppet, Chef, and other automation tools

Project Homepage: chocolatey.org

2. Installation#

Prerequisites#

Windows 7+ / Windows Server 2003+
PowerShell v2+ (v5+ recommended)
.NET Framework 4.8+ (installed automatically on modern Windows)

Install Chocolatey#

Check the execution policy:

Get-ExecutionPolicy

If it returns Restricted, set a permissive policy:

Set-ExecutionPolicy AllSigned
# Or for the current session only:
Set-ExecutionPolicy Bypass -Scope Process

Install Chocolatey:

Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Verify the installation:

choco --version

Install Location#

Chocolatey installs to C:\ProgramData\chocolatey by default. Packages are stored in C:\ProgramData\chocolatey\lib.

3. Package Operations#

Search for Packages#

# Search the community repository
choco search <query>

# Search with exact name match
choco search <package-name> --exact

# List all versions of a package
choco search <package-name> --all-versions

Install Packages#

# Install a package
choco install <package-name> -y

# Install a specific version
choco install <package-name> --version=<version> -y

# Install multiple packages
choco install git vscode firefox -y

# Install with specific parameters passed to the installer
choco install <package-name> --params "'/NoDesktopShortcut /InstallDir:D:\Apps'" -y

# Install without prompts (non-interactive)
choco install <package-name> -y --no-progress

Upgrade Packages#

# Upgrade a specific package
choco upgrade <package-name> -y

# Upgrade all installed packages
choco upgrade all -y

# Upgrade but exclude specific packages
choco upgrade all --except="'<package1>,<package2>'" -y

# Check for outdated packages (dry run)
choco outdated

Uninstall Packages#

# Uninstall a package
choco uninstall <package-name> -y

# Uninstall and remove dependencies
choco uninstall <package-name> --remove-dependencies -y

# Uninstall a specific version
choco uninstall <package-name> --version=<version> -y

List Installed Packages#

# List all locally installed packages
choco list

# List with version details
choco list --include-programs

Package Info#

# Show detailed information about a package
choco info <package-name>

4. Package Sources#

# List configured sources
choco source list

# Add a new source
choco source add --name="<source-name>" --source="<url-or-path>"

# Add a source with authentication
choco source add --name="<source-name>" --source="<url>" `
    --user="<username>" --password="<password>"

# Add a local folder as a source
choco source add --name="local" --source="C:\packages"

# Disable a source
choco source disable --name="<source-name>"

# Enable a source
choco source enable --name="<source-name>"

# Remove a source
choco source remove --name="<source-name>"

Default source: https://community.chocolatey.org/api/v2/ (named chocolatey).

5. Configuration#

# List all configuration settings
choco config list

# Set a configuration value
choco config set --name="<setting>" --value="<value>"

# Unset a configuration value
choco config unset --name="<setting>"

Common Settings#

Setting	Default	Description
`cacheLocation`	(system temp)	Custom cache directory for downloads
`commandExecutionTimeoutSeconds`	2700	Maximum time for a package operation
`proxy`	(empty)	Proxy server URL
`proxyUser`	(empty)	Proxy authentication username

Feature Flags#

# List all features
choco feature list

# Enable a feature
choco feature enable --name="<feature>"

# Disable a feature
choco feature disable --name="<feature>"

Feature	Default	Description
`allowGlobalConfirmation`	Disabled	Skip `-y` flag; auto-confirm all prompts
`useRememberedArgumentsForUpgrades`	Disabled	Reuse install arguments during upgrades
`exitOnRebootDetected`	Disabled	Exit with code 350 when reboot is needed
`failOnAutoUninstaller`	Disabled	Fail the package if auto-uninstaller fails

6. Version Pinning#

Prevent specific packages from being upgraded:

# Pin a package to its current version
choco pin add --name="<package-name>"

# Pin to a specific version
choco pin add --name="<package-name>" --version="<version>"

# List all pinned packages
choco pin list

# Remove a pin
choco pin remove --name="<package-name>"

Pinned packages are skipped during choco upgrade all.

7. Package Creation#

Quick Start#

# Generate a package template
choco new <package-name>

This creates a directory structure:

<package-name>/
  <package-name>.nuspec
  tools/
    chocolateyInstall.ps1
    chocolateyUninstall.ps1

Nuspec File#

The .nuspec file contains package metadata:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">
  <metadata>
    <id>my-package</id>
    <version>1.0.0</version>
    <title>My Package</title>
    <authors>Your Name</authors>
    <description>Package description.</description>
    <tags>utility tool</tags>
    <dependencies>
      <dependency id="dotnetfx" version="4.8.0" />
    </dependencies>
  </metadata>
</package>

Install Script#

Edit tools/chocolateyInstall.ps1:

$ErrorActionPreference = 'Stop'

$packageArgs = @{
    packageName    = $env:ChocolateyPackageName
    fileType       = 'msi'
    url            = 'https://example.com/installer.msi'
    checksum       = '<sha256-hash>'
    checksumType   = 'sha256'
    silentArgs     = '/qn /norestart'
    validExitCodes = @(0, 3010)
}

Install-ChocolateyPackage @packageArgs

Build and Test#

# Pack the package
choco pack <package-name>/<package-name>.nuspec

# Test install from local file
choco install <package-name> --source="." -y

# Push to a repository
choco push <package-name>.<version>.nupkg --source="<repository-url>" --api-key="<key>"

8. Automated Installation Scripts#

Create a script to set up a new machine with all required software:

# setup.ps1 - New machine provisioning
# Run as Administrator

# Install Chocolatey if not present
if (-not (Get-Command choco -ErrorAction SilentlyContinue)) {
    Set-ExecutionPolicy Bypass -Scope Process -Force
    [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
    iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
}

# Development tools
choco install git -y
choco install vscode -y
choco install nodejs-lts -y
choco install python3 -y

# Utilities
choco install 7zip -y
choco install firefox -y
choco install winscp -y
choco install putty -y

# Communication
choco install slack -y
choco install zoom -y

Write-Host "Setup complete. Restart recommended."

Export and Import Package Lists#

# Export installed packages to a config file
choco export -o="packages.config"

# Install all packages from a config file
choco install packages.config -y

The packages.config format:

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="git" version="2.44.0" />
  <package id="vscode" />
  <package id="firefox" />
</packages>

9. Proxy Configuration#

# Set proxy server
choco config set --name="proxy" --value="http://<proxy-host>:<port>"

# Set proxy credentials
choco config set --name="proxyUser" --value="<username>"
choco config set --name="proxyPassword" --value="<password>"

# Bypass proxy for specific addresses
choco config set --name="proxyBypassList" --value="'internal.example.com,*.local'"

# Use system proxy settings
choco config set --name="proxy" --value="system"

# Remove proxy configuration
choco config unset --name="proxy"
choco config unset --name="proxyUser"
choco config unset --name="proxyPassword"

10. Organizational Deployment#

Internal Repository#

For enterprise use, host an internal package repository to control which packages are available:

Chocolatey Server - simple NuGet-compatible server (open source)
ProGet / Nexus / Artifactory - full-featured artifact repositories with Chocolatey support
Network share - use a UNC path or local folder as a package source

# Disable the community repository
choco source disable --name="chocolatey"

# Add internal repository
choco source add --name="internal" --source="https://nuget.internal.example.com/api/v2/" `
    --user="<svc-account>" --password="<password>"

Chocolatey for Business (C4B)#

The commercial edition adds:

Package Builder (create packages from installers automatically)
Package Internalizer (download and internalize community packages)
Self-Service GUI for end users
Central Management Dashboard
Virus scanning integration
Runtime malware protection

Configuration Management Integration#

Chocolatey integrates with common automation tools:

# Ansible
# - Use win_chocolatey module
# - Example: win_chocolatey: name=git state=present

# Puppet
# - Use chocolatey provider
# - Example: package { 'git': provider => 'chocolatey' }

# DSC (Desired State Configuration)
# - Use cChoco DSC resource

11. Chocolatey vs Winget#

Feature	Chocolatey	Winget
Package count	~10,000+ community	~5,000+ (Microsoft + community)
Built into Windows	No (separate install)	Yes (Windows 10 1809+)
Package creation	NuGet-based `.nuspec`	YAML manifests
Enterprise features	C4B (paid)	Limited
Dependency resolution	Yes	Basic
Version pinning	Yes	No
Automation/scripting	Mature PowerShell integration	Improving
Internal repositories	Yes (NuGet feeds)	Limited
Silent install	Packages handle it	`-h` flag
Configuration management	Ansible, Puppet, DSC	Limited

Both tools can coexist on the same system. Choose based on your needs: Chocolatey for mature automation and enterprise scenarios, winget for simple interactive installs.

Troubleshooting#

Issue	Cause	Solution
`choco` not recognized	PATH not updated after install	Close and reopen terminal; verify `C:\ProgramData\chocolatey\bin` is in PATH
Install fails with checksum error	Download corrupted or URL changed	Use `--ignore-checksums` temporarily; report to package maintainer
Access denied during install	Not running as Administrator	Open PowerShell as Administrator
Package install hangs	Installer waiting for user input	Ensure package uses silent install arguments; check `/qn` or `/S` flags
Upgrade fails for pinned package	Package is version-pinned	Run `choco pin remove --name="<package>"` then upgrade
Source returns 401/403	Authentication issue	Verify credentials with `choco source list`; re-add source with correct credentials
Proxy blocking downloads	Corporate proxy not configured	Set proxy with `choco config set --name="proxy" --value="<url>"`
Old package version installs	Cached package	Clear cache: `choco cache remove` or delete `C:\ProgramData\chocolatey\cache`