win_updates - Download and install Windows updates

New in version 2.0.


  • Searches, downloads, and installs Windows updates synchronously by automating the Windows Update client


parameter required default choices comments
no [u'CriticalUpdates', u'SecurityUpdates', u'UpdateRollups']
  • Application
  • Connectors
  • CriticalUpdates
  • DefinitionUpdates
  • DeveloperKits
  • FeaturePacks
  • Guidance
  • SecurityUpdates
  • ServicePacks
  • Tools
  • UpdateRollups
  • Updates
A scalar or list of categories to install updates from
If set, win_updates will append update progress to the specified file. The directory must already exist.
no installed
  • installed
  • searched
Controls whether found updates are returned as a list or actually installed.
This module also supports Ansible check mode, which has the same effect as setting state=searched


# Install all security, critical, and rollup updates
- win_updates:
      - SecurityUpdates
      - CriticalUpdates
      - UpdateRollups

# Install only security updates
- win_updates:
    category_names: SecurityUpdates

# Search-only, return list of found updates (if any), log to c:\ansible_wu.txt
- win_updates:
    category_names: SecurityUpdates
    state: searched
    log_path: c:\ansible_wu.txt

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name description returned type sample
installed_update_count The number of updates successfully installed success int 2
reboot_required True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot) success boolean True
failed_update_count The number of updates that failed to install always int 0
found_update_count The number of updates found needing to be applied success int 3
updates List of updates that were found/installed success dictionary None
name description returned type sample
kb A list of KB article IDs that apply to the update always list of strings ['3004365']
title Display name always string Security Update for Windows Server 2012 R2 (KB3004365)
failure_hresult_code The HRESULT code from a failed update on install failure boolean 2147942402
id Internal Windows Update GUID always string (guid) fb95c1c8-de23-4089-ae29-fd3351d55421
installed Was the update successfully installed always boolean True



  • win_updates must be run by a user with membership in the local Administrators group
  • win_updates will use the default update service configured for the machine (Windows Update, Microsoft Update, WSUS, etc)
  • win_updates does not manage reboots, but will signal when a reboot is required with the reboot_required return value.
  • win_updates can take a significant amount of time to complete (hours, in some cases). Performance depends on many factors, including OS version, number of updates, system load, and update server load.


This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.


This module is maintained by those with core commit privileges

For more information on what this means please read Module Support

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.