Ansible download_file: Download Files from URL (get_url Module Guide)

Ansible download_file: Download Files from URL (get_url Module Guide)

The ansible.builtin.get_url module downloads files from HTTP, HTTPS, and FTP URLs to remote hosts. It's the Ansible equivalent of wget or curl, with built-in checksum validation, authentication, and idempotency.

See also: Master Ansible Automation Platform: Simplify IT Management

Basic File Download

---
- name: Download file examples
  hosts: all
  become: true
  tasks:
    - name: Download a file
      ansible.builtin.get_url:
        url: https://example.com/app-2.0.tar.gz
        dest: /tmp/app-2.0.tar.gz
        mode: '0644'

Key Parameters

| Parameter | Description | Example | |-----------|-------------|---------| | url | URL to download (required) | https://example.com/file.tar.gz | | dest | Destination path (required) | /tmp/file.tar.gz | | mode | File permissions | '0755' | | owner | File owner | root | | group | File group | root | | checksum | Verify file integrity | sha256:abc123... | | timeout | Download timeout (seconds) | 30 | | force | Always re-download | true | | headers | HTTP headers | {Authorization: "Bearer token"} | | url_username | HTTP basic auth username | admin | | url_password | HTTP basic auth password | secret | | validate_certs | Verify SSL certificates | true (default) | | backup | Backup existing file | true | | tmp_dest | Temporary download location | /tmp |

See also: Ansible troubleshooting - Module Failure on Windows-target

Download with Checksum Validation

Always verify integrity for security-critical downloads:

- name: Download with SHA256 checksum
  ansible.builtin.get_url:
    url: https://releases.hashicorp.com/terraform/1.9.0/terraform_1.9.0_linux_amd64.zip
    dest: /tmp/terraform.zip
    checksum: sha256:abc123def456...
- name: Download with checksum from URL
  ansible.builtin.get_url:
    url: https://example.com/release.tar.gz
    dest: /tmp/release.tar.gz
    checksum: "sha256:https://example.com/release.tar.gz.sha256"
- name: Download with MD5 checksum
  ansible.builtin.get_url:
    url: https://example.com/package.deb
    dest: /tmp/package.deb
    checksum: md5:d41d8cd98f00b204e9800998ecf8427e

Download and Extract Archive

Combine get_url with unarchive:

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

Or download and extract in one step:

- name: Download and extract directly
  ansible.builtin.unarchive:
    src: https://example.com/app-2.0.tar.gz
    dest: /opt/app/
    remote_src: true

See also: Ansible 'Destination Does Not Exist' Error: Fix Path Issues

Download Scripts and Execute

- name: Download install script
  ansible.builtin.get_url:
    url: https://get.docker.com
    dest: /tmp/get-docker.sh
    mode: '0755'
- name: Run install script
  ansible.builtin.command: /tmp/get-docker.sh
  args:
    creates: /usr/bin/docker

Authenticated Downloads

HTTP Basic Auth

- name: Download from authenticated endpoint
  ansible.builtin.get_url:
    url: https://artifacts.example.com/releases/app.jar
    dest: /opt/app/app.jar
    url_username: "{{ vault_artifact_user }}"
    url_password: "{{ vault_artifact_pass }}"
    force_basic_auth: true

Bearer Token / Custom Headers

- name: Download with bearer token
  ansible.builtin.get_url:
    url: https://api.github.com/repos/org/repo/releases/assets/12345
    dest: /tmp/release.tar.gz
    headers:
      Authorization: "Bearer {{ github_token }}"
      Accept: "application/octet-stream"
- name: Download from S3 pre-signed URL
  ansible.builtin.get_url:
    url: "{{ s3_presigned_url }}"
    dest: /opt/data/dataset.csv

Conditional Downloads

- name: Download only if not already present
  ansible.builtin.get_url:
    url: https://example.com/large-file.iso
    dest: /opt/images/large-file.iso
    force: false  # Default — skips if dest exists and size matches
- name: Always re-download (force fresh copy)
  ansible.builtin.get_url:
    url: https://example.com/config.json
    dest: /etc/app/config.json
    force: true
- name: Download based on condition
  ansible.builtin.get_url:
    url: "https://example.com/{{ ansible_architecture }}/binary"
    dest: /usr/local/bin/app
    mode: '0755'
  when: ansible_os_family == "Debian"

Download Multiple Files

- name: Download multiple packages
  ansible.builtin.get_url:
    url: "{{ item.url }}"
    dest: "{{ item.dest }}"
    checksum: "{{ item.checksum | default(omit) }}"
    mode: "{{ item.mode | default('0644') }}"
  loop:
    - url: https://example.com/app.tar.gz
      dest: /tmp/app.tar.gz
      checksum: sha256:abc123...
    - url: https://example.com/config.yml
      dest: /etc/app/config.yml
    - url: https://example.com/binary
      dest: /usr/local/bin/tool
      mode: '0755'

Error Handling

- name: Download with retry and timeout
  ansible.builtin.get_url:
    url: https://slow-server.example.com/large-file.tar.gz
    dest: /tmp/large-file.tar.gz
    timeout: 120
  retries: 3
  delay: 10
  register: download_result
  until: download_result is succeeded
- name: Handle download failure gracefully
  block:
    - name: Try primary download
      ansible.builtin.get_url:
        url: https://primary.example.com/package.deb
        dest: /tmp/package.deb
  rescue:
    - name: Fall back to mirror
      ansible.builtin.get_url:
        url: https://mirror.example.com/package.deb
        dest: /tmp/package.deb

Proxy Configuration

- 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,.internal.com"

get_url vs uri vs command curl

| Method | Use Case | |--------|----------| | get_url | Download files to disk (best for most cases) | | uri | API calls, REST requests (returns response body) | | command: curl | Last resort (not idempotent) |

FAQ

How do I download a file with Ansible?

Use the ansible.builtin.get_url module with url and dest parameters. It downloads from HTTP/HTTPS/FTP and supports checksum validation, authentication, and idempotent operation.

Is Ansible get_url idempotent?

Yes. By default, get_url checks if the destination file exists and has the correct size. It skips re-downloading unchanged files. Use force: true to always re-download, or checksum for content-based validation.

How do I verify downloaded file integrity in Ansible?

Use the checksum parameter: checksum: sha256:abc123.... You can also point to a checksum file URL. This ensures the downloaded file matches the expected hash before placing it.

What is the Ansible equivalent of wget?

The ansible.builtin.get_url module is the Ansible equivalent of wget and curl. It downloads files from URLs with built-in checksum validation, authentication, and proxy support.

How do I download and extract a tar.gz with Ansible?

Use get_url to download, then unarchive with remote_src: true to extract. Or use unarchive directly with an HTTP URL as src to download and extract in one step.

Conclusion

The ansible.builtin.get_url module is the standard way to download files in Ansible. Always use checksum for security-critical files, combine with unarchive for archives, and leverage retries for unreliable sources.

Related Articles

• Ansible uri Module: HTTP REST API Calls • Ansible unarchive Module: Extract Archives • Ansible copy Module: Copy Files Local to Remote