What you'll learn
- How to Extract an Archive in Ansible?
- Basic Usage
- Extract Local Archive to Remote Host
- Extract Archive Already on Remote Host
- Download and Extract from URL
- Parameters Reference
- Idempotent Extraction
- Using creates Parameter
- Using stat + when Conditional
- Include and Exclude Files
The `ansible.builtin.unarchive` module extracts compressed archives (tar, tar.gz, tar.bz2, tar.xz, zip) on remote hosts. It copies from the Ansible controller or downloads from a URL, extracts to a target directory, and handles permissions and ownership — all in a single task.
How to Extract an Archive in Ansible?
I'm going to show you a live Playbook and some simple Ansible code.
I'm Luca Berton and welcome to today's episode of Ansible Pilot.
The full name is `ansible.builtin.unarchive`, part of the builtin collection shipped with Ansible. It's stable, works across Linux distributions, and handles `.zip` files using `unzip` as well as `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, and `.tar.zst` files using `gtar`.
For Windows targets, use the `community.windows.win_unzip` module instead.
Basic Usage
Extract Local Archive to Remote Host
By default, `src` is a path on the Ansible controller. The archive is copied to the remote host, then extracted:
```yaml
- name: Extract application archive
ansible.builtin.unarchive:
src: files/myapp-2.1.0.tar.gz
dest: /opt/myapp/
owner: appuser
group: appuser
mode: '0755'
become: true
```
Extract Archive Already on Remote Host
When the archive is already on the remote host, set `remote_src: true`:
```yaml
- name: Extract remote archive
ansible.builtin.unarchive:
src: /tmp/myapp-2.1.0.tar.gz
dest: /opt/myapp/
remote_src: true
become: true
```
Download and Extract from URL
Set `remote_src: true` with an HTTP/HTTPS URL as `src` to download and extract in one step:
```yaml
- name: Download and extract from URL
ansible.builtin.unarchive:
src: https://github.com/prometheus/prometheus/releases/download/v2.52.0/prometheus-2.52.0.linux-amd64.tar.gz
dest: /opt/
remote_src: true
become: true
```
Parameters Reference
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `src` | string | Archive path (local, remote, or URL) | **Required** |
| `dest` | string | Target extraction directory | **Required** |
| `remote_src` | boolean | Source is on remote host or URL | `false` |
| `owner` | string | Set owner of extracted files | — |
| `group` | string | Set group of extracted files | — |
| `mode` | string | Set permissions of extracted files | — |
| `creates` | string | Skip if this path exists (idempotency) | — |
| `exclude` | list | Files/dirs to exclude from extraction | — |
| `include` | list | Files/dirs to include in extraction | — |
| `keep_newer` | boolean | Don't overwrite newer files on remote | `false` |
| `extra_opts` | list | Extra command-line options for tar/unzip | — |
| `list_files` | boolean | Return list of extracted files in result | `false` |
| `validate_certs` | boolean | Validate SSL certs for HTTPS URLs | `true` |
Idempotent Extraction
Using creates Parameter
The `creates` parameter is the recommended way to make extraction idempotent:
```yaml
- name: Extract application (idempotent)
ansible.b