Ansible win_get_url — Download Files on Windows Hosts

Introduction

The ansible.windows.win_get_url module downloads files from HTTP, HTTPS, and FTP URLs to Windows remote hosts. It's the Windows equivalent of ansible.builtin.get_url — handles authentication, proxy settings, checksum validation, and TLS certificate handling.

Quick Reference

# Basic download
- ansible.windows.win_get_url:
    url: https://example.com/installer.msi
    dest: C:\Temp\installer.msi

# Download with checksum verification
- ansible.windows.win_get_url:
    url: https://example.com/app.zip
    dest: C:\Temp\app.zip
    checksum: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

# Force re-download
- ansible.windows.win_get_url:
    url: https://releases.example.com/latest.zip
    dest: C:\Deploy\latest.zip
    force: true

Parameters

Parameter	Default	Description
`url`	(required)	URL to download
`dest`	(required)	Destination path on Windows host
`checksum`	—	Verify file integrity (algorithm:hash)
`checksum_url`	—	URL containing checksum
`force`	false	Re-download even if file exists
`headers`	—	Custom HTTP headers
`url_username`	—	HTTP basic auth username
`url_password`	—	HTTP basic auth password
`proxy_url`	—	HTTP proxy URL
`proxy_username`	—	Proxy auth username
`proxy_password`	—	Proxy auth password
`validate_certs`	true	Validate SSL certificates
`timeout`	10	Connection timeout in seconds
`use_default_credential`	false	Use Windows default credential
`use_proxy`	true	Use system proxy settings

Common Patterns

Download and Install MSI

- name: Download installer
  ansible.windows.win_get_url:
    url: https://download.example.com/agent-2.0.msi
    dest: C:\Temp\agent-2.0.msi
    checksum: sha256:abc123...

- name: Install MSI package
  ansible.windows.win_package:
    path: C:\Temp\agent-2.0.msi
    state: present

Download with Authentication

- name: Download from private repository
  ansible.windows.win_get_url:
    url: https://artifacts.internal.com/builds/app-latest.zip
    dest: C:\Deploy\app-latest.zip
    url_username: deploy-user
    url_password: "{{ artifact_password }}"
    force_basic_auth: true

Download Through Corporate Proxy

- name: Download through proxy
  ansible.windows.win_get_url:
    url: https://github.com/project/releases/download/v1.0/tool.exe
    dest: C:\Tools\tool.exe
    proxy_url: http://proxy.corp.com:8080
    proxy_username: "{{ proxy_user }}"
    proxy_password: "{{ proxy_pass }}"

Download with Custom Headers (Bearer Token)

- name: Download from API with token
  ansible.windows.win_get_url:
    url: https://api.github.com/repos/org/repo/releases/assets/12345
    dest: C:\Temp\release.zip
    headers:
      Authorization: "Bearer {{ github_token }}"
      Accept: application/octet-stream

Conditional Download (Only If Absent)

- name: Check if file exists
  ansible.windows.win_stat:
    path: C:\Tools\kubectl.exe
  register: kubectl_file

- name: Download kubectl if missing
  ansible.windows.win_get_url:
    url: https://dl.k8s.io/release/v1.28.0/bin/windows/amd64/kubectl.exe
    dest: C:\Tools\kubectl.exe
  when: not kubectl_file.stat.exists

Download Multiple Files

- name: Download utilities
  ansible.windows.win_get_url:
    url: "{{ item.url }}"
    dest: "{{ item.dest }}"
    checksum: "{{ item.checksum | default(omit) }}"
  loop:
    - url: https://example.com/tool1.exe
      dest: C:\Tools\tool1.exe
    - url: https://example.com/tool2.zip
      dest: C:\Temp\tool2.zip
      checksum: sha256:def456...

Self-Signed Certificate

- name: Download from internal server with self-signed cert
  ansible.windows.win_get_url:
    url: https://internal-server.local/package.zip
    dest: C:\Temp\package.zip
    validate_certs: false  # Only for internal/dev servers

win_get_url vs get_url

Feature	win_get_url	get_url
Platform	Windows	Linux/macOS
Connection	WinRM/PSRP	SSH
Paths	`C:\Temp\file.exe`	`/tmp/file.tar.gz`
Backend	.NET WebClient	urllib/requests
Proxy	Windows system proxy	Environment vars
Auth	Windows credentials	HTTP basic/digest

Checksum Validation

# Inline checksum
- ansible.windows.win_get_url:
    url: https://example.com/app.zip
    dest: C:\Temp\app.zip
    checksum: sha256:e3b0c44298fc1c149afbf4c8996fb924...

# Checksum from URL
- ansible.windows.win_get_url:
    url: https://example.com/app.zip
    dest: C:\Temp\app.zip
    checksum_url: https://example.com/app.zip.sha256

# Supported algorithms: md5, sha1, sha256, sha384, sha512

Troubleshooting

Error	Cause	Fix
`The request was aborted: Could not create SSL/TLS secure channel`	TLS version mismatch	Update .NET / set TLS 1.2 via `[Net.ServicePointManager]::SecurityProtocol`
`407 Proxy Authentication Required`	Proxy needs credentials	Set `proxy_username` and `proxy_password`
`404 Not Found`	URL changed or wrong	Verify URL in browser
File always re-downloaded	No `checksum` set, `force: true`	Add checksum for idempotency
`Access denied` to dest path	Insufficient permissions	Run with `become: true` or use accessible path

Best Practices

Always use checksums — ensures integrity and idempotency
Use C:\Temp\ for downloads — clean up after installation
Set validate_certs: true in production — only disable for internal dev
Use vault for credentials — url_password, proxy_password
Set reasonable timeout — increase for large files or slow connections
Clean up installers — delete temp files after package installation

Conclusion

ansible.windows.win_get_url downloads files to Windows hosts from HTTP/HTTPS/FTP URLs. Always validate checksums for idempotent downloads. Handle corporate proxies with proxy_url and authentication parameters. Use force: true only when you need to re-download regardless of existing files. Pair with win_package for download-and-install workflows.