community.windows.win_unzip module – Unzips compressed files and archives on the Windows node

Note

This module is part of the community.windows collection (version 3.1.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.windows. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.windows.win_unzip.

Synopsis

• Unzips compressed files and archives.

• Supports .zip files natively via the .NET BCL.

• Supports tar-based formats (.tar, .tar.gz/.tgz, .tar.bz2/.tbz2, .tar.xz/.txz) via tar.exe as of community.windows 3.2.0. tar.exe ships with Windows 10 build 17063 and later and Windows Server 2019 and later, with no additional software required.

• Supports other formats (.gz, .bz2, .msu and others) via the PowerShell Community Extensions (PSCX) module. PSCX is also required when using the recurse or password options, and for tar-based formats prior to community.windows 3.2.0.

• For non-Windows targets, use the ansible.builtin.unarchive module instead.

Requirements

The below requirements are needed on the host that executes this module.

• PSCX for formats other than .zip and tar-based, or when using recurse or password. Also required for tar-based formats prior to community.windows 3.2.0, or on older OS versions which did not ship tar.exe.

Parameters

Parameter	Comments
creates path	If this file or directory exists the specified src will not be extracted.
delete_archive aliases: rm boolean	Remove the zip file, after unzipping. Choices: false ← (default) true
dest path / required	Destination of zip file (provide absolute path of directory). If it does not exist, the directory will be created.
password string	If a zip file is encrypted with password. Passing a value to a password parameter requires the PSCX module to be installed.
recurse boolean	Recursively expand zipped files within the src file. Setting to a value of yes requires the PSCX module to be installed. Choices: false ← (default) true
src path / required	File to be unzipped (provide absolute path).

Notes

Note

• This module is not really idempotent, it will extract the archive every time, and report a change.

• For tar-based formats (.tar, .tar.gz, .tgz, .tar.bz2, .tbz2, .tar.xz, .txz) the module uses %SystemRoot%\System32\tar.exe when available, requiring no extra software. On older systems where tar.exe is not present, the module falls back to PSCX.

• For all other compression types, or when recurse or password are used, the PowerShellCommunityExtensions (PSCX) module is required. If the destination directory does not exist, it will be created before unzipping the file. Specifying rm parameter will force removal of the src file after extraction.

See Also

See also

ansible.builtin.unarchive

The official documentation on the ansible.builtin.unarchive module.

Examples

# This unzips a library that was downloaded with win_get_url, and removes the file after extraction
# $ ansible -i hosts -m win_unzip -a "src=C:\LibraryToUnzip.zip dest=C:\Lib remove=yes" all

- name: Unzip a bz2 (BZip) file
  community.windows.win_unzip:
    src: C:\Users\Phil\Logs.bz2
    dest: C:\Users\Phil\OldLogs
    creates: C:\Users\Phil\OldLogs

- name: Unzip gz log
  community.windows.win_unzip:
    src: C:\Logs\application-error-logs.gz
    dest: C:\ExtractedLogs\application-error-logs

- name: Extract a tar.gz archive (uses tar.exe on Windows 10/Server 2019+, no extra software needed)
  community.windows.win_unzip:
    src: C:\Downloads\package.tar.gz
    dest: C:\Extracted\package
    delete_archive: true

# Unzip .zip file, recursively decompresses the contained .gz files and removes all unneeded compressed files after completion.
- name: Recursively decompress GZ files in ApplicationLogs.zip
  community.windows.win_unzip:
    src: C:\Downloads\ApplicationLogs.zip
    dest: C:\Application\Logs
    recurse: true
    delete_archive: true

# PSCX is required for: non-tar formats other than .zip, recurse, and password-protected archives.
- name: Install PSCX
  community.windows.win_psmodule:
    name: Pscx
    state: present

- name: Unzip .7z file which is password encrypted
  community.windows.win_unzip:
    src: C:\Downloads\ApplicationLogs.7z
    dest: C:\Application\Logs
    password: abcd
    delete_archive: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
dest string	The provided destination path Returned: always Sample: "C:\\ExtractedLogs\\application-error-logs"
removed boolean	Whether the module did remove any files during task run Returned: always Sample: true
src string	The provided source path Returned: always Sample: "C:\\Logs\\application-error-logs.gz"

Authors

• Phil Schwartz (@schwartzmx)

Collection links

• Issue Tracker
• Repository (Sources)
• Communication