Ansible unarchive Module: Extract tar, zip, gz Archives (Complete Guide)

Ansible unarchive Module: Extract tar, zip, gz Archives (Complete Guide)

The ansible.builtin.unarchive module unpack compressed archives on remote hosts. This guide covers all common use cases with practical playbook examples.

See also: Ansible unarchive Module: Extract tar.gz, zip Archives on Remote Hosts

Extract Local Archive to Remote Host

- name: Deploy application from local archive
  ansible.builtin.unarchive:
    src: files/myapp-2.1.0.tar.gz
    dest: /opt/myapp/
    owner: deploy
    group: deploy
    mode: '0755'

Extract Remote Archive

- name: Download and extract release
  ansible.builtin.unarchive:
    src: "https://github.com/myorg/myapp/releases/download/v{{ version }}/myapp-{{ version }}.tar.gz"
    dest: /opt/myapp/releases/{{ version }}/
    remote_src: true
    creates: /opt/myapp/releases/{{ version }}/bin/myapp

See also: Ansible win_unzip Module: Extract ZIP Archives on Windows (Guide)

Extract with Specific Options

- name: Extract specific files only
  ansible.builtin.unarchive:
    src: /tmp/backup.tar.gz
    dest: /opt/restore/
    remote_src: true
    include:
      - 'config/'
      - 'data/important.db'
    extra_opts:
      - '--strip-components=1'

Extract zip File

- name: Extract zip archive
  ansible.builtin.unarchive:
    src: files/webapp.zip
    dest: /var/www/html/
    owner: www-data
    group: www-data

See also: AAP 2.6 Tested Deployment Models: Growth & Enterprise Topologies Guide

FAQ

How do I extract a tar.gz file in Ansible?

Use ansible.builtin.unarchive with src (archive path) and dest (target directory). Add remote_src: true if the archive is already on the remote host.

Can Ansible download and extract an archive in one step?

Yes. Set src to an HTTP/HTTPS URL and remote_src: true. Ansible downloads and extracts in one task. Use creates to skip if already extracted.

What archive formats does unarchive support?

Ansible unarchive supports tar, tar.gz, tar.bz2, tar.xz, zip, and gz. The remote host needs the appropriate tools installed (tar, unzip, gzip, bzip2, xz).

Conclusion

The ansible.builtin.unarchive module is a versatile tool for unpack compressed archives on remote hosts. Use the examples above as starting points and adapt them to your infrastructure needs.

Related Articles

• Ansible copy Module: Copy Files to Hosts • Ansible get_url: Download Files

Parameters Reference

| Parameter | Description | Default | |---|---|---| | src | Path to archive (local or remote) | required | | dest | Destination directory | required | | remote_src | Archive is already on remote host | false | | creates | Skip extraction if path exists | — | | exclude | List of files/dirs to exclude | — | | include | List of files/dirs to include | — | | owner | Set owner on extracted files | — | | group | Set group on extracted files | — | | mode | Set permissions on extracted files | — |

Common Examples

- name: Extract archives with Ansible
  hosts: all
  become: true
  tasks:
    # Extract local archive to remote
    - name: Deploy application from tarball
      ansible.builtin.unarchive:
        src: files/myapp-v2.0.tar.gz
        dest: /opt/myapp/
        owner: appuser
        group: appuser
# Extract remote archive (already on target)
    - name: Extract downloaded archive
      ansible.builtin.unarchive:
        src: /tmp/release.zip
        dest: /opt/
        remote_src: true
# Download and extract in one step
    - name: Download and extract Go
      ansible.builtin.unarchive:
        src: https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
        dest: /usr/local/
        remote_src: true
        creates: /usr/local/go/bin/go
# Extract specific files only
    - name: Extract config files only
      ansible.builtin.unarchive:
        src: backup.tar.gz
        dest: /etc/myapp/
        remote_src: true
        include:
          - "config/"
          - "*.conf"
        exclude:
          - "logs/"

Idempotent Extraction with creates

    - name: Extract only if not already done
      ansible.builtin.unarchive:
        src: https://example.com/tool-v3.tar.gz
        dest: /opt/
        remote_src: true
        creates: /opt/tool-v3/bin/tool

FAQ

What archive formats does unarchive support?

ansible.builtin.unarchive supports .tar, .tar.gz, .tgz, .tar.bz2, .tar.xz, .zip, and .gz. The target host needs the appropriate tools (tar, unzip, etc.).

How do I make unarchive idempotent?

Use the creates parameter. If the specified path exists, the task is skipped. This prevents re-extracting on every run.

Can unarchive download and extract from a URL?

Yes. Set src to a URL and remote_src: true. Ansible downloads the file to the target and extracts it.