Top 6 Uses of Ansible Unarchive Module You Haven’t Tried Yet

The Ansible unarchive module helps you automate the process of extracting files from compressed archives such as .tar.gz, .zip, or .bz2. It’s an essential tool for tasks like deploying application packages, extracting configuration files, or setting up software from archives.

In this guide, you’ll learn how to use unarchive with real-world YAML examples covering local files, remote URLs, permission settings, and more.

Basic Syntax

The basic syntax of the Unarchive module is simple. Below is a breakdown of all the available parameters:

- name: Unarchive a file
  ansible.builtin.unarchive:
    src: /path/to/archive.tar.gz      
    dest: /path/to/destination/       
    remote_src: no                    
    creates: /path/to/created/file    
    list_files: no                    
    extra_opts:                       
      - "--strip-components=1"
    keep_newer: no                    
    mode: '0644'

Here’s a short explanation of each part of the provided playbook:

• name: Unarchive a file: Defines the name of the task, which is to unarchive a file.
• ansible.builtin.unarchive: Uses the unarchive module to extract an archive.
• src: Specifies the local source file path (/path/to/archive.tar.gz).
• dest: Defines the destination directory (/path/to/destination/) where the archive will be extracted.
• remote_src: Set to no, meaning the source file is on the local machine, not remote.
• creates: Specifies a file that will be checked; if it exists, the extraction is skipped.
• list_files: Set to no, meaning it will not list the files in the archive before extraction.
• extra_opts: Provides extra options for extraction (–strip-components=1 removes one leading directory from the extracted files).
• keep_newer: Set to no, meaning existing files in the destination will be overwritten.
• mode: Sets the permissions of the extracted files to ‘0644’.

Example 1: Extract a Local Archive to a Specific Directory

To unarchive a file to a specific directory on a remote host, you can use the following playbook:

---
- name: Unarchive file example
  hosts: webservers
  tasks:
    - name: Unarchive the tar.gz file
      ansible.builtin.unarchive:
        src: /tmp/my_archive.tar.gz
        dest: /var/www/html/

In this example playbook, the my_archive.tar.gz file located in the /tmp directory is uncompressed into the /var/www/html/ directory on the remote host.

Example 2: Download and Extract from a Remote URL

The Unarchive module also supports downloading and uncompressing files from remote URLs. This is useful for fetching files directly from the internet and deploying them on your servers.

---
- name: Unarchive from remote URL example
  hosts: webservers
  tasks:
    - name: Download and unarchive file from URL
      ansible.builtin.unarchive:
        src: https://example.com/files/my_archive.tar.gz
        dest: /var/www/html/
        remote_src: yes

In this example, the my_archive.tar.gz file is downloaded from the specified URL and uncompressed into the /var/www/html/ directory on the remote host.

Example 3: Unarchive File Already on Remote Host

If both the source and destination are remote, set remote_src to yes:

---
- name: Unarchive remote source to remote destination
  hosts: webservers
  tasks:
    - name: Unarchive the file from remote source
      ansible.builtin.unarchive:
        src: /remote/path/to/archive.zip
        dest: /var/www/html/
        remote_src: yes

This playbook extracts the contents of the archive located at /remote/path/to/archive.zip on the remote machine itself (indicated by remote_src: yes) into the /var/www/html/ directory on the same machine. This is useful for deploying files or applications directly to the web server.

Example 4: Set Permissions on Extracted Files

You may need to adjust file permissions after unarchiving. This can be done using the mode parameter or by adding a separate task with a file module to change permissions:

---
- name: Unarchive and set permissions
  hosts: webservers
  tasks:
    - name: Unarchive the file
      ansible.builtin.unarchive:
        src: /tmp/my_archive.tar.gz
        dest: /var/www/html/
        mode: '0755'
    - name: Set permissions
      ansible.builtin.file:
        path: /var/www/html/
        state: directory
        mode: '0755'

This playbook unarchives a file to /var/www/html/ on remote web servers, setting extracted files’ permissions to 0755 and ensuring the destination directory has the same permissions.

Example 5: Make Unarchive Idempotent

Ansible modules are idempotent by nature, meaning they ensure the desired state without repeating actions if the state is already achieved.

---
- name: Idempotent unarchive example
  hosts: webservers
  tasks:
    - name: Check if the file exists
      ansible.builtin.stat:
        path: /var/www/html/index.html
      register: stat_result

    - name: Unarchive only if necessary
      ansible.builtin.unarchive:
        src: /tmp/my_archive.tar.gz
        dest: /var/www/html/
      when: not stat_result.stat.exists

This playbook checks if /var/www/html/index.html exists and only unarchives /tmp/my_archive.tar.gz to /var/www/html/ if the file does not already exist.

Common Issues & Fixes

Error Message	Likely Cause & Fix
src file not found	Set remote_src: yes for remote paths or URLs
Files keep overwriting	Use creates: or stat: to make unarchive idempotent
File permissions not preserved	Use mode: or run file: module post-extraction

Conclusion

The Ansible unarchive module makes it simple to automate file extraction across servers, whether you’re pulling archives from a remote location or deploying packages from your local machine.

Combine it with mode, creates, and file modules to make your playbooks safe, idempotent, and production-ready.

FAQs

1. Can the unarchive module download and extract files from a URL?

Yes, by setting the remote_src parameter to yes, you can specify a URL for the archive, allowing it to be downloaded and extracted directly on the remote server.

2. How do I ensure existing files are not overwritten when using the unarchive module?

Use the extra_opts parameter with suitable extraction options to prevent overwriting existing files, or ensure creates is used to check if a target file already exists.

3. Can I use the unarchive module to create target directories automatically?

Yes, if the dest directory doesn’t exist, the unarchive module will create it automatically before extracting the files.