ansible.builtin.unarchive – Unpacks an archive after (optionally) copying it from the local machine¶
Note
This module is part of ansible-base
and included in all Ansible
installations. In most cases, you can use the short module name
unarchive even without specifying the collections:
keyword.
Despite that, we recommend you use the FQCN for easy linking to the module
documentation and to avoid conflicting with other collections that may have
the same module name.
New in version 1.4: of ansible.builtin
Synopsis¶
The
unarchive
module unpacks an archive. It will not unpack a compressed file that does not contain an archive.By default, it will copy the source file from the local system to the target before unpacking.
Set
remote_src=yes
to unpack an archive which already exists on the target.If checksum validation is desired, use ansible.builtin.get_url or ansible.builtin.uri instead to fetch the file and set
remote_src=yes
.For Windows targets, use the community.windows.win_unzip module instead.
Note
This module has a corresponding action plugin.
Parameters¶
Notes¶
Note
Requires
zipinfo
andgtar
/unzip
command on target host.Can handle .zip files using
unzip
as well as .tar, .tar.gz, .tar.bz2 and .tar.xz files usinggtar
.Does not handle .gz files, .bz2 files or .xz files that do not contain a .tar archive.
Uses gtar’s
--diff
arg to calculate if changed or not. If thisarg
is not supported, it will always unpack the archive.Existing files/directories in the destination which are not in the archive are not touched. This is the same behavior as a normal archive extraction.
Existing files/directories in the destination which are not in the archive are ignored for purposes of deciding if the archive should be unpacked or not.
Supports
check_mode
.
See Also¶
See also
- community.general.archive
The official documentation on the community.general.archive module.
- community.general.iso_extract
The official documentation on the community.general.iso_extract module.
- community.windows.win_unzip
The official documentation on the community.windows.win_unzip module.
Examples¶
- name: Extract foo.tgz into /var/lib/foo
ansible.builtin.unarchive:
src: foo.tgz
dest: /var/lib/foo
- name: Unarchive a file that is already on the remote machine
ansible.builtin.unarchive:
src: /tmp/foo.zip
dest: /usr/local/bin
remote_src: yes
- name: Unarchive a file that needs to be downloaded (added in 2.0)
ansible.builtin.unarchive:
src: https://example.com/example.zip
dest: /usr/local/bin
remote_src: yes
- name: Unarchive a file with extra options
ansible.builtin.unarchive:
src: /tmp/foo.zip
dest: /usr/local/bin
extra_opts:
- --transform
- s/^xxx/yyy/
Authors¶
Michael DeHaan