AnsibleByExample

Fix Ansible WinRM Connection Errors

intermediateAnsible ErrorAnsible TroubleshootingWindowsWinRM
2026-03-032By Luca Berton

Lesson 1 of 20 in Production Playbooks

Production Playbooks and Troubleshooting — full curriculum
  1. 1. Advanced Playbook Structure & Execution Strategies
  2. 2. Deep Dive: Variable Precedence & Best Practices
  3. 3. Jinja2 Templating Beyond Basics
  4. 4. Advanced Conditionals
  5. 5. Loops Masterclass
  6. 6. Blocks, Rescue, Always (Error Handling)
  7. 7. Handlers Advanced
  8. 8. Change Control: changed_when, failed_when
  9. 9. Tags and Selective Runs
  10. 10. Performance Tuning
  11. 11. Delegation Patterns
  12. 12. Local Actions and Remote Actions
  13. 13. Dynamic Inventory & Runtime Host Management
  14. 14. Includes & Imports (Structuring Large Codebases)
  15. 15. Role Design Patterns
  16. 16. Ansible Galaxy & Collections in Real Projects
  17. 17. Working with APIs (uri + JSON workflows)
  18. 18. Testing and Linting (Quality Gates)
  19. 19. Advanced Debugging Playbook Failures
  20. 20. Capstone: Multi-Stage Deployment
View path overview →

Fix Ansible WinRM Connection Errors

The Error

fatal: [windows-host]: UNREACHABLE! => {
    "changed": false,
    "msg": "winrm or requests is not installed: No module named 'winrm'",
    "unreachable": true
}

Step 1: Install pywinrm

pip install pywinrm
# Or with Kerberos support
pip install pywinrm[kerberos]

Step 2: Configure Inventory

[windows]
win1 ansible_host=192.168.1.100

[windows:vars]
ansible_user=Administrator
ansible_password=SecureP@ss123
ansible_connection=winrm
ansible_winrm_transport=ntlm
ansible_winrm_server_cert_validation=ignore
ansible_port=5986

Step 3: Enable WinRM on Windows

Run this PowerShell script on the Windows host as Administrator:

# Quick setup (HTTP - for testing only)
winrm quickconfig -force

# Enable HTTPS (production)
$cert = New-SelfSignedCertificate -DnsName $(hostname) -CertStoreLocation Cert:\LocalMachine\My
winrm create winrm/config/Listener?Address=*+Transport=HTTPS "@{Hostname=`"$(hostname)`";CertificateThumbprint=`"$($cert.Thumbprint)`"}"

# Allow basic auth
Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true
Set-Item -Path WSMan:\localhost\Service\AllowUnencrypted -Value $true

# Open firewall
New-NetFirewallRule -Name "WinRM-HTTPS" -DisplayName "WinRM HTTPS" -Protocol TCP -LocalPort 5986 -Action Allow

Or use the Ansible-provided script:

Invoke-WebRequest -Uri https://raw.githubusercontent.com/ansible/ansible-documentation/main/examples/scripts/ConfigureRemotingForAnsible.ps1 -OutFile ConfigureRemotingForAnsible.ps1
.\ConfigureRemotingForAnsible.ps1

Common Errors

Connection Refused (port 5985/5986)

# Check if WinRM is listening
Test-NetConnection -ComputerName windows-host -Port 5986

Certificate Validation Error

# Ignore cert validation (self-signed certs)
ansible_winrm_server_cert_validation=ignore

Authentication Failed

# Try different transport methods
ansible_winrm_transport=ntlm      # Most common
ansible_winrm_transport=basic     # Simple but less secure
ansible_winrm_transport=kerberos  # Domain environments
ansible_winrm_transport=credssp   # CredSSP delegation

Timeout Error

ansible_winrm_operation_timeout_sec=60
ansible_winrm_read_timeout_sec=120

Test Connection

ansible windows -m win_ping -i inventory.ini

Conclusion

WinRM setup requires configuration on both the Ansible controller (pywinrm) and the Windows host (WinRM listener). Use HTTPS in production, NTLM for authentication, and the Ansible-provided setup script for quick configuration.

All Tutorials