AnsibleByExample

Ansible Chocolatey — Windows Software

Beginneransibleinstallwindowspackage
2024-01-014By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

Introduction

Chocolatey is the package manager for Windows — like apt for Ubuntu or dnf for RHEL. Combined with Ansible's win_chocolatey module, you can automate software installation, updates, and management across your entire Windows fleet from a single playbook.

Module Reference

Full name: chocolatey.chocolatey.win_chocolatey Collection: chocolatey.chocolatey

Install the collection:

ansible-galaxy collection install chocolatey.chocolatey

Key Parameters

ParameterTypeRequiredDescription
namelist/stringYesPackage name(s) to manage
statestringNopresent, latest, absent, downgrade, reinstalled
versionstringNoSpecific version to install
pinnedboolNoPin package to prevent upgrades
sourcestringNoCustom package source URL
install_argsstringNoArguments passed to the native installer
package_paramsstringNoParameters passed to the Chocolatey package
allow_prereleaseboolNoAllow prerelease versions
forceboolNoForce reinstall even if already installed
timeoutintNoTimeout in seconds (default: 2700)

State Values

StateBehavior
presentInstall if not present (default)
latestInstall or upgrade to latest version
absentUninstall the package
downgradeDowngrade to specified version
reinstalledForce reinstall

Basic Playbook

---
- name: Install software on Windows
  hosts: windows
  gather_facts: false
  tasks:
    - name: Install packages
      chocolatey.chocolatey.win_chocolatey:
        name:
          - git
          - notepadplusplus
          - 7zip
          - vscode
        state: present

Practical Examples

Install Specific Versions

- name: Install specific Python version
  chocolatey.chocolatey.win_chocolatey:
    name: python3
    version: "3.11.5"
    state: present

- name: Install specific Java JDK
  chocolatey.chocolatey.win_chocolatey:
    name: openjdk17
    version: "17.0.8"
    state: present
    pinned: true  # Prevent automatic upgrades

Developer Workstation Setup

- name: Set up developer workstation
  hosts: dev_machines
  gather_facts: false
  vars:
    dev_tools:
      - git
      - vscode
      - python3
      - nodejs-lts
      - docker-desktop
      - postman
      - winscp
      - putty
    browsers:
      - googlechrome
      - firefox
    utilities:
      - 7zip
      - notepadplusplus
      - everything
      - greenshot
      - winmerge

  tasks:
    - name: Install development tools
      chocolatey.chocolatey.win_chocolatey:
        name: "{{ dev_tools }}"
        state: present

    - name: Install browsers
      chocolatey.chocolatey.win_chocolatey:
        name: "{{ browsers }}"
        state: present

    - name: Install utilities
      chocolatey.chocolatey.win_chocolatey:
        name: "{{ utilities }}"
        state: present

Update All Packages

- name: Update all Chocolatey packages
  chocolatey.chocolatey.win_chocolatey:
    name: all
    state: latest

Uninstall Software

- name: Remove unwanted software
  chocolatey.chocolatey.win_chocolatey:
    name:
      - bloatware-app
      - old-tool
    state: absent

Install from Custom Source

For organizations with a private Chocolatey repository:

- name: Install from internal repository
  chocolatey.chocolatey.win_chocolatey:
    name: internal-app
    source: https://choco.internal.example.com/api/v2/
    state: present

Pass Arguments to Native Installer

- name: Install SQL Server with custom args
  chocolatey.chocolatey.win_chocolatey:
    name: sql-server-express
    state: present
    install_args: "/INSTANCENAME=SQLEXPRESS /SECURITYMODE=SQL"
    package_params: "/IAcceptSQLServerLicenseTerms"
    timeout: 3600  # SQL install can take a while

Ensuring Chocolatey is Installed

The win_chocolatey module automatically installs Chocolatey if it's not present. However, you can manage it explicitly:

- name: Install Chocolatey itself
  chocolatey.chocolatey.win_chocolatey:
    name: chocolatey
    state: present

- name: Configure Chocolatey settings
  chocolatey.chocolatey.win_chocolatey_config:
    name: cacheLocation
    state: present
    value: C:\Temp\choco-cache

- name: Set Chocolatey source
  chocolatey.chocolatey.win_chocolatey_source:
    name: internal
    source: https://choco.internal.example.com/api/v2/
    state: present
    priority: 1

Gathering Package Information

- name: Get list of 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 }}"

- name: Check if specific package is installed
  ansible.builtin.debug:
    msg: "Git version: {{ choco_facts.ansible_facts.packages | selectattr('package', 'equalto', 'git') | map(attribute='version') | first }}"

Common Errors

"Chocolatey is not installed"

Normally auto-handled. If it fails:

- name: Install Chocolatey manually
  ansible.windows.win_shell: |
    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'))

Timeout on Large Installations

- name: Install large package with extended timeout
  chocolatey.chocolatey.win_chocolatey:
    name: visualstudio2022community
    state: present
    timeout: 7200  # 2 hours

Conclusion

The win_chocolatey module brings Linux-style package management to Windows automation. Install, update, pin, and remove software across your Windows fleet with simple YAML playbooks. For enterprise environments, combine it with a private Chocolatey repository and win_chocolatey_config for centralized package management. The module handles Chocolatey installation automatically, making it truly zero-config to get started.

All Tutorials