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
The number of updates successfully installed
success int 2
True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot)
success boolean True
The number of updates that failed to install
always int 0
The number of updates found needing to be applied
success int 3
List of updates that were found/installed
success complex None
name description returned type sample
A list of KB article IDs that apply to the update
always list of strings ['3004365']
Display name
always string Security Update for Windows Server 2012 R2 (KB3004365)
The HRESULT code from a failed update
on install failure boolean 2147942402
Internal Windows Update GUID
always string (guid) fb95c1c8-de23-4089-ae29-fd3351d55421
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.
  • win_updates runs the module as a scheduled task, this task is set to start and continue to run even if the Windows host swaps to battery power. This behaviour was changed from Ansible 2.4, before this the scheduled task would fail to start on battery power.


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

Maintenance Info

For more information about Red Hat’s this support of this module, please refer to this knowledge base article<>

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