Introduction
Chocolatey is the package manager for Windows — like apt or yum for Linux. Ansible's win_chocolatey module lets you install, update, and remove any of the 9,000+ Chocolatey packages across your Windows fleet. This guide covers single packages, bulk installs, version pinning, and common deployment patterns.
Prerequisites
| Requirement | Details |
|---|---|
| Ansible collection | chocolatey.chocolatey |
| Windows target | WinRM configured (setup guide) |
| Chocolatey | Auto-installed by the module if missing |
# Install the collection
ansible-galaxy collection install chocolatey.chocolatey
Module Parameters
| Parameter | Type | Description |
|---|---|---|
name | string/list | Package name(s) from Chocolatey repository |
state | string | present, latest, absent, downgrade, reinstalled |
version | string | Specific version to install |
source | string | Custom Chocolatey source/feed URL |
install_args | string | Arguments passed to the native installer |
package_params | string | Parameters passed to the Chocolatey package |
allow_prerelease | bool | Allow pre-release versions |
force | bool | Force reinstall even if already installed |
ignore_checksums | bool | Skip package checksum validation |
timeout | int | Timeout in seconds for the install |
Basic Examples
Install a Single Package
- name: Install Google Chrome
chocolatey.chocolatey.win_chocolatey:
name: googlechrome
state: present
Install Multiple Packages
- name: Install standard workstation software
chocolatey.chocolatey.win_chocolatey:
name:
- googlechrome
- firefox
- vscode
- 7zip
- notepadplusplus
- git
- python3
state: present
Install Specific Version
- name: Install specific Chrome version
chocolatey.chocolatey.win_chocolatey:
name: googlechrome
version: "120.0.6099.130"
state: present
pinned: true # Prevent auto-update
Update to Latest
- name: Update all installed packages
chocolatey.chocolatey.win_chocolatey:
name: all
state: latest
Remove a Package
- name: Remove Internet Explorer
chocolatey.chocolatey.win_chocolatey:
name: ie11
state: absent
Practical Patterns
Developer Workstation Setup
---
- name: Configure developer workstation
hosts: dev_workstations
tasks:
- name: Install development tools
chocolatey.chocolatey.win_chocolatey:
name:
- git
- vscode
- python3
- nodejs
- docker-desktop
- postman
- winscp
- putty
state: present
- name: Install VS Code extensions
ansible.windows.win_shell: |
code --install-extension ms-python.python
code --install-extension redhat.ansible
code --install-extension ms-vscode-remote.remote-ssh
Install from Custom Source
- name: Install from internal Chocolatey server
chocolatey.chocolatey.win_chocolatey:
name: internal-app
source: https://choco.internal.company.com/api/v2/
state: present
Install with Native Installer Arguments
- name: Install Chrome silently with custom args
chocolatey.chocolatey.win_chocolatey:
name: googlechrome
state: present
install_args: "/silent /install"
ignore_checksums: true
Pin Package Version (Prevent Updates)
- name: Install and pin Java version
chocolatey.chocolatey.win_chocolatey:
name: jdk8
version: "8.0.302"
state: present
pinned: true
Complete Workstation Playbook
---
- name: Standard Windows workstation setup
hosts: windows_workstations
vars:
standard_packages:
- googlechrome
- firefox
- 7zip
- vlc
- adobereader
dev_packages:
- git
- vscode
- python3
- nodejs-lts
tasks:
- name: Ensure Chocolatey is installed
chocolatey.chocolatey.win_chocolatey:
name: chocolatey
state: present
- name: Install standard packages
chocolatey.chocolatey.win_chocolatey:
name: "{{ standard_packages }}"
state: present
- name: Install developer packages
chocolatey.chocolatey.win_chocolatey:
name: "{{ dev_packages }}"
state: present
when: "'developers' in group_names"
- name: Get installed packages
chocolatey.chocolatey.win_chocolatey_facts:
register: choco_facts
- name: Show installed packages
ansible.builtin.debug:
msg: "{{ choco_facts.ansible_facts.packages | map(attribute='package') | list }}"
Popular Chocolatey Packages
| Package Name | Software |
|---|---|
googlechrome | Google Chrome |
firefox | Mozilla Firefox |
vscode | Visual Studio Code |
git | Git for Windows |
python3 | Python 3 |
nodejs-lts | Node.js LTS |
7zip | 7-Zip |
docker-desktop | Docker Desktop |
putty | PuTTY SSH client |
notepadplusplus | Notepad++ |
winscp | WinSCP |
vlc | VLC Media Player |
Troubleshooting
Chocolatey Not Found
The module auto-installs Chocolatey, but if it fails:
- name: Manually install Chocolatey
ansible.windows.win_shell: |
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
Package Install Timeout
- name: Install large package with extended timeout
chocolatey.chocolatey.win_chocolatey:
name: visualstudio2022community
state: present
timeout: 3600 # 1 hour
Checksum Mismatch
- name: Install ignoring checksum
chocolatey.chocolatey.win_chocolatey:
name: somepackage
state: present
ignore_checksums: true
Related Articles
- Configure Windows for Ansible (WinRM)
- Test Windows: win_ping
- Copy Files to Windows: win_copy
- Install Packages on Linux: yum Module
- PowerShell Sudo Fix
Conclusion
Use chocolatey.chocolatey.win_chocolatey to install any Windows software: name: googlechrome + state: present. Pass a list to name for bulk installs, use version + pinned: true for version control, and source for internal package servers. The module auto-installs Chocolatey if it's missing. For developer workstations, combine with win_shell for VS Code extensions and other post-install configuration.