The ansible.windows.win_updates module installs Windows updates on a target. It does not decide which hosts go first, how reboots are sequenced, whether a server is healthy once it returns, or what happens when it does not. A production run in AWX needs those decisions made explicitly and written down around the module. AWX contributes repeatable execution against a defined inventory and a job record you can audit. Everything else is design you own.
This article sets out that design, and marks which points the official documentation settles and which ones it leaves to you.
As an Amazon Associate I earn from qualifying purchases.
What win_updates does and what it requires
The module drives the Windows Update client to search for, download and install updates. The update service it uses is whichever one the target is configured for: Windows Update, Microsoft Update or WSUS. That matters because the set of patches you can get is defined by that service, not by your playbook.
Prerequisites
- The user executing the task must belong to the target’s local Administrators group.
- The module ships in the
ansible.windowscollection, not inansible-core, so the collection has to be installed separately. The module documentation lists it underansible.windows3.8.0. Pin that version so runs are reproducible:
ansible-galaxy collection install ansible.windows:==3.8.0In AWX, the collection must also be present in the execution environment that your job template uses. Installing it on a workstation does not make it available to jobs.
#1 Best Overall
Selection and state
- Updates can be scoped by category, then refined with accept and reject lists.
- The module supports search-only and download-only states in addition to installing.
- Results report found, installed and failed update counts, the filtered results, and whether a reboot is required.
Run duration
Runs vary. The module documentation says a run can take hours, depending on the operating-system version, the number of updates, system load and update-server load. Build maintenance windows around a range rather than a single expected duration.
The reboot contract
By default the module does not reboot. It reports the need through the reboot_required return value. The Ansible Community Documentation for the module states:
“By default ansible.windows.win_updates does not manage reboots, but will signal when a reboot is required with the reboot_required return value.”
Free tools Windows power users keep installed
One-click scans. No signup required.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Setting reboot: true lets the module reboot and continue installing updates. That option has two limits. Async cannot be used with it, and the documentation cautions that services may still be settling immediately after the reboot.
Two reboot patterns compared
| Aspect | reboot: true inside win_updates |
Separate conditional win_reboot task |
|---|---|---|
| Number of tasks | One task handles installation and reboot | An install task, then a reboot task that runs only when reboot_required is true |
| Async | Cannot be used with this setting | The documented async restriction is tied to reboot: true, so it does not apply here |
| Control over sequencing | The module decides when the reboot happens and when installation resumes | You decide what runs between installation and reboot, and in what order |
| Visibility in job output | Installation and reboot appear within one task result | The reboot appears as its own task, so its outcome is recorded separately |
| Post-reboot settling | The documentation warns that services may still be settling, so checks are still needed | The same warning applies; a successful reboot task does not show that services are ready |
win_updates or win_hotfix
The Ansible Windows usage guide separates these two modules by the source of the update.
| Aspect | win_updates | win_hotfix |
|---|---|---|
| Update source | The update service configured on the target (Windows Update, Microsoft Update or WSUS) | An individual update or hotfix file that has been downloaded locally |
| Scope | Catalogue updates selected by category, with accept and reject lists | One named update |
| Inputs you supply | Category names, filters, and Administrators membership on the target | The hotfix file itself |
| Typical fit | Routine patching against the catalogue your update service offers | A single fix you already hold as a file |
The update task
This pattern separates installation from reboot: the update task runs with the default no-reboot behaviour, and a conditional step handles the reboot. The category names are an example, not a recommendation for your policy.
Rank #4
- name: Patch Windows hosts in the current batch
hosts: windows_batch_1
tasks:
- name: Install security and critical updates without rebooting
ansible.windows.win_updates:
category_names:
- SecurityUpdates
- CriticalUpdates
reboot: false
register: update_result
- name: Reboot only if the update module reports it is needed
ansible.windows.win_reboot: {}
when: update_result.reboot_required
What AWX adds, and where it stops
Job records give you traceability
Each AWX job shows its status and output, along with execution environment and execution node details. That tells you what ran, where it ran and in which environment. It does not show that the patched application is healthy.
Inventories define the target group
An AWX inventory can be maintained by hand or sourced from supported cloud and infrastructure inventory plugins. Use a dynamic source when an external system is the authority on which hosts exist. The Update on Launch setting refreshes an inventory before a job runs. It has cache and dependency behaviour you should understand before relying on it for a patch group, because a refresh changes which hosts the job targets.
Best Value
Forks control parallelism
AWX best-practice guidance suggests increasing job-template forks when host counts are large. That is tuning advice, not a concurrency value that is safe for every production estate. Set forks from how many hosts can be unavailable at the same time without breaking the services they support.
Fact caching
Fact caching on job templates is off by default. The AWX guidance recommends using AWX’s own fact cache rather than a custom cache configured in ansible.cfg, which would compete with it. Cached facts can help workflows that need inventory host facts, but they describe the host as it was last collected. They are not evidence that a patch installed.
The rollout sequence
- Define the first group. Take the target group from your source of truth and keep the first run narrow. Decide how stale, missing and newly provisioned hosts are handled, and use the inventory settings above so that the group refreshes only the way you intend.
- Fix the job template. Pin the project to a version-controlled playbook, and fix the inventory, credentials and execution environment. Record the AWX version and the collection version alongside each run.
- Keep the update policy in the playbook. Category names, accept and reject lists, and a written rule for any exception belong in version control, not in someone’s memory. Use win_hotfix only for a single locally downloaded file.
- Choose reboot handling explicitly. Use one of the two patterns in the comparison table. Do not combine
reboot: truewith async. After a reboot, let services settle and confirm that the host is reachable before any application check runs. - Review per-host results, then run your checks. Read the found, installed and failed counts, the filtered results and the reboot requirement for each host. Then run the checks in the verification section, and record how failed or unreachable hosts are isolated and retried.
- Expand only after the first group passes. Move to the next batch only when the first group meets acceptance criteria you have written down. Set forks and batch size from your fleet and the risk to its services.
Verification: what a successful job does not prove
A completed job means the playbook ran without error. It does not mean the workload is back to normal. The documentation supplies return values but no health check, escalation path or rollback policy, so define these before the first run. Typical checks include:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Critical Windows services are in their expected state on each patched host.
- Application endpoints or test transactions respond as expected once the reboot has settled.
- Event logs show no new errors from the patching window.
- Hosts that failed to patch or did not return are excluded from the next batch until an named owner has reviewed them.
Also write down the escalation contact and the recovery steps for a host that does not come back. Neither the module nor AWX provides them.
Quick Recap
Connection and execution problems
- The SSH connection drops during the run. Windows Updates can restart the network adapter. The module documentation’s example sets
ServerAliveInterval=30with control master disabled. For example, in host or group variables:ansible_ssh_common_args='-o ServerAliveInterval=30 -o ControlMaster=no'. - The background process does not start or behaves inconsistently. By default the module launches its work as a background process through Windows Task Scheduler. If Task Scheduler is unavailable or unreliable on the target, the documentation suggests using
become.
What is and isn’t established
- The module and AWX documentation describe behaviour, not outcomes. They do not establish a patch success rate, time saving or vulnerability reduction, so none is claimed here.
- The AWX documentation used for this article is version 24.6.1. Menu labels and features change between releases, so check them against the AWX version you run.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
