Ansible get_url Module Complete Reference: Checksums, Auth, Proxies & Retries

The ansible.builtin.get_url module downloads files from HTTP, HTTPS, and FTP URLs to remote hosts. It handles checksums, authentication, proxies, timeouts, and conditional downloads — the Ansible equivalent of wget or curl.

Basic Usage

Download a File

- name: Download application binary
  ansible.builtin.get_url:
    url: https://example.com/releases/myapp-2.1.0.tar.gz
    dest: /tmp/myapp-2.1.0.tar.gz

Download with Checksum Verification

# SHA256 checksum
- name: Download with SHA256 verification
  ansible.builtin.get_url:
    url: https://example.com/releases/myapp-2.1.0.tar.gz
    dest: /tmp/myapp-2.1.0.tar.gz
    checksum: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
# MD5
- name: Download with MD5
  ansible.builtin.get_url:
    url: https://example.com/file.zip
    dest: /tmp/file.zip
    checksum: md5:d41d8cd98f00b204e9800998ecf8427e
# Checksum from URL
- name: Download with checksum file
  ansible.builtin.get_url:
    url: https://example.com/releases/myapp.tar.gz
    dest: /tmp/myapp.tar.gz
    checksum: "sha256:https://example.com/releases/myapp.tar.gz.sha256"

Set Ownership and Permissions

- name: Download script with execute permission
  ansible.builtin.get_url:
    url: https://example.com/scripts/setup.sh
    dest: /opt/scripts/setup.sh
    owner: deploy
    group: deploy
    mode: '0755'
  become: true

See also: Ansible Delete File & Remove File: file Module absent State Guide

Common Parameters

| Parameter | Description | Default | |-----------|-------------|---------| | url | Download URL (required) | — | | dest | Destination path (required) | — | | checksum | Verify download integrity | — | | mode | File permissions | — | | owner | File owner | — | | group | File group | — | | force | Download even if file exists | false | | timeout | Download timeout (seconds) | 10 | | url_username | HTTP Basic Auth username | — | | url_password | HTTP Basic Auth password | — | | headers | Custom HTTP headers | — | | validate_certs | Verify SSL certificates | true | | backup | Create backup of existing file | false | | tmp_dest | Temp download directory | — |

Authentication

HTTP Basic Auth

- name: Download from authenticated endpoint
  ansible.builtin.get_url:
    url: https://releases.example.com/enterprise/myapp.tar.gz
    dest: /tmp/myapp.tar.gz
    url_username: "{{ vault_download_user }}"
    url_password: "{{ vault_download_pass }}"
    force_basic_auth: true

Bearer Token

- name: Download with Bearer token
  ansible.builtin.get_url:
    url: https://api.example.com/releases/latest
    dest: /tmp/release.tar.gz
    headers:
      Authorization: "Bearer {{ vault_api_token }}"

GitHub Release (Private Repo)

- name: Download from private GitHub release
  ansible.builtin.get_url:
    url: "https://api.github.com/repos/myorg/myapp/releases/assets/{{ asset_id }}"
    dest: /tmp/myapp.tar.gz
    headers:
      Authorization: "token {{ vault_github_token }}"
      Accept: application/octet-stream

See also: Ansible 2.17.0-rc1: Elevating Automation with ‘Gallows Pole’

Proxy Configuration

# Per-task proxy
- name: Download through proxy
  ansible.builtin.get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
  environment:
    http_proxy: http://proxy.example.com:3128
    https_proxy: http://proxy.example.com:3128
    no_proxy: localhost,127.0.0.1
# Play-level proxy
- hosts: all
  environment:
    https_proxy: http://proxy.example.com:3128
  tasks:
    - name: Download packages
      ansible.builtin.get_url:
        url: "{{ item.url }}"
        dest: "{{ item.dest }}"
      loop:
        - { url: "https://example.com/a.tar.gz", dest: "/tmp/a.tar.gz" }
        - { url: "https://example.com/b.tar.gz", dest: "/tmp/b.tar.gz" }

Idempotent Downloads

# Only downloads if file doesn't exist or checksum differs
- name: Download (idempotent via checksum)
  ansible.builtin.get_url:
    url: https://example.com/myapp.tar.gz
    dest: /tmp/myapp.tar.gz
    checksum: sha256:abc123...
# Force re-download every time
- name: Always download latest
  ansible.builtin.get_url:
    url: https://example.com/latest/myapp.tar.gz
    dest: /tmp/myapp.tar.gz
    force: true
# Conditional download
- name: Check if binary exists
  ansible.builtin.stat:
    path: /opt/myapp/bin/myapp
  register: binary
- name: Download only if missing
  ansible.builtin.get_url:
    url: https://example.com/myapp.tar.gz
    dest: /tmp/myapp.tar.gz
  when: not binary.stat.exists

See also: ansible_date_time: Access Date, Time & Timestamp Facts in Ansible

Real-World Patterns

Download and Extract

- name: Download application
  ansible.builtin.get_url:
    url: "https://github.com/org/app/releases/download/v{{ version }}/app-{{ version }}.tar.gz"
    dest: "/tmp/app-{{ version }}.tar.gz"
    checksum: "sha256:{{ app_checksum }}"
- name: Extract application
  ansible.builtin.unarchive:
    src: "/tmp/app-{{ version }}.tar.gz"
    dest: /opt/app/
    remote_src: true

Download Multiple Files

- name: Download tool binaries
  ansible.builtin.get_url:
    url: "{{ item.url }}"
    dest: "{{ item.dest }}"
    mode: '0755'
    checksum: "{{ item.checksum }}"
  loop:
    - url: https://example.com/tool1
      dest: /usr/local/bin/tool1
      checksum: sha256:abc...
    - url: https://example.com/tool2
      dest: /usr/local/bin/tool2
      checksum: sha256:def...

Install Binary from GitHub

- name: Install kubectl
  ansible.builtin.get_url:
    url: "https://dl.k8s.io/release/v{{ kubectl_version }}/bin/linux/amd64/kubectl"
    dest: /usr/local/bin/kubectl
    mode: '0755'
    checksum: "sha256:https://dl.k8s.io/release/v{{ kubectl_version }}/bin/linux/amd64/kubectl.sha256"
  become: true

Handle Self-Signed Certificates

# Disable certificate validation (testing/internal only)
- name: Download from internal server
  ansible.builtin.get_url:
    url: https://internal.example.com/package.tar.gz
    dest: /tmp/package.tar.gz
    validate_certs: false
# Better: Add CA certificate
- name: Download with custom CA
  ansible.builtin.get_url:
    url: https://internal.example.com/package.tar.gz
    dest: /tmp/package.tar.gz
    ca_path: /etc/ssl/certs/internal-ca.pem

Windows Equivalent

# For Windows, use win_get_url
- name: Download on Windows
  ansible.windows.win_get_url:
    url: https://example.com/installer.msi
    dest: C:\temp\installer.msi
    checksum: abc123...
    checksum_algorithm: sha256

FAQ

How do I download a file with Ansible?

Use the get_url module: ansible.builtin.get_url: url=https://example.com/file.tar.gz dest=/tmp/file.tar.gz. It supports HTTP, HTTPS, and FTP. Add checksum for integrity verification.

How do I verify checksums with get_url?

Use the checksum parameter: checksum: sha256:abc123.... You can also point to a checksum URL: checksum: "sha256:https://example.com/file.sha256". Ansible verifies after download and fails if mismatched.

Is get_url idempotent?

Yes — if the destination file exists and matches the checksum, it's skipped. Without a checksum, it checks file size and modification time. Use force: true to always re-download.

How do I download through a proxy?

Set proxy environment variables on the task: environment: {https_proxy: "http://proxy:3128"}. Or configure system-wide in group_vars.

What is the difference between get_url and uri?

get_url downloads files to disk. uri makes HTTP requests and returns the response body — better for API calls. Use get_url for downloading files, uri for REST API interactions.

Conclusion

• url + dest — Download file to remote host • checksum: sha256:... — Verify integrity (always use in production) • mode/owner/group — Set file permissions on download • force: true — Re-download even if file exists • environment: {https_proxy: ...} — Download through proxy • Windows: Use ansible.windows.win_get_url

Related Articles

• Ansible unarchive Module: Extract Archives • Ansible uri Module: HTTP/REST API Calls • Ansible copy Module