Uncompress collection for ansible. Lets you download an uncompress .gz and .bz2 files which currently isn't possible with the unarchive built-in module. https://galaxy.ansible.com/ui/repo/published/compscidr/uncompress/

Motivated by the push-back against .gz .bz2 not being supported for compressed files: ansible/ansible-modules-core#3241 (comment)

and the existance of this project: https://github.com/vadikgo/uncompress.

Updating the existing project to support installation via a meta/requirements.yml file and then submitting to ansible galaxy so that it can be found and installed easily.

ansible-galaxy collection install compscidr.uncompress

Add the following to requirements.yml

collections:
- name: compscidr.uncompress

Then run ansible-galaxy install -r requirements.yml

Add the following to your requirements.yml file:

collections:
  - name: git+https://github.com/compscidr/ansible-uncompress.git,main

Then run ansible-galaxy install -r requirements.yml

Ansible's built-in unarchive module handles archives (like .tar.gz), but refuses to decompress plain compressed files (like .gz alone). This module fills that gap.

ansible.builtin.unarchive can:

• ✅ .tar.gz - decompress and extract
• ✅ .tar.bz2 - decompress and extract
• ✅ .tar.xz - decompress and extract
• ✅ .zip - extract
• ❌ .gz alone - won't handle (no archive inside)
• ❌ .bz2 alone - won't handle (no archive inside)
• ❌ .xz alone - won't handle (no archive inside)

compscidr.uncompress can:

• ✅ .gz - decompress single files
• ✅ .bz2 - decompress single files
• ✅ .xz - decompress single files
• ✅ .lzma - decompress single files
• ✅ .tar.gz - decompress to .tar (but not extract)
• ❌ Won't extract archives - use unarchive for that

Use compscidr.uncompress for:

• Single compressed files: binary.gz, config.bz2, data.xz
• When you need just the uncompressed file, not archive extraction
• Example: compressed executables, config files, data files

Use ansible.builtin.unarchive for:

• Archive files: .tar.gz, .tar.bz2, .tar.xz, .zip
• When you want to extract multiple files from an archive
• Example: application packages, source code archives

Important: This module handles decompression (removing compression like .gz), not unarchiving (extracting archive contents like .tar). If you uncompress archive.tar.gz, you'll get archive.tar - you'd still need to extract the tar archive separately (see examples below).

Specify the exact destination file path:

---
- name: Install cheat binary
  become: true
  compscidr.uncompress.uncompress:
    copy: false
    src: https://github.com/cheat/cheat/releases/download/4.3.1/cheat-linux-amd64.gz
    dest: /usr/local/bin/cheat
    mode: '755'

- name: Uncompress local file
  compscidr.uncompress.uncompress:
    src: /tmp/myfile.bz2
    dest: /opt/myapp/data.txt
    copy: true

New in v0.0.8: Specify a directory and let the module automatically derive the filename from the source:

---
- name: Uncompress to directory (filename auto-derived)
  compscidr.uncompress.uncompress:
    src: foo.gz
    dest: /tmp/
  # Results in /tmp/foo

- name: Download and uncompress to directory
  compscidr.uncompress.uncompress:
    copy: false
    src: https://example.com/app.bz2
    dest: /usr/local/bin/
  # Results in /usr/local/bin/app

- name: Handle URLs with query parameters
  compscidr.uncompress.uncompress:
    copy: false
    src: https://example.com/file.gz?version=1.0&token=abc
    dest: /opt/myapp/
  # Query parameters are stripped - results in /opt/myapp/file

- name: Uncompress tar.gz (strips .gz, keeps .tar)
  compscidr.uncompress.uncompress:
    src: archive.tar.gz
    dest: /tmp/
  # Results in /tmp/archive.tar

The module returns the destination path, making it easy to use in subsequent tasks:

---
- name: Uncompress file to directory
  compscidr.uncompress.uncompress:
    src: myapp.gz
    dest: /opt/
  register: result

- name: Use the uncompressed file
  ansible.builtin.debug:
    msg: "File uncompressed to {{ result.dest }}"
  # Outputs: File uncompressed to /opt/myapp

For .tar.gz files, you typically want both decompression AND extraction. Here are your options:

This is the simplest approach - unarchive handles both decompression and extraction in one step:

---
- name: Download and extract tar.gz archive
  ansible.builtin.unarchive:
    src: https://example.com/myapp.tar.gz
    dest: /opt/myapp/
    remote_src: true
  # Automatically decompresses and extracts all files to /opt/myapp/

If you need to decompress first and extract later (e.g., to inspect the tar file):

---
- name: Step 1 - Uncompress .tar.gz to .tar
  compscidr.uncompress.uncompress:
    copy: false
    src: https://example.com/myapp.tar.gz
    dest: /tmp/
  register: uncompress_result
  # Results in /tmp/myapp.tar

- name: Step 2 - Extract the tar archive
  ansible.builtin.unarchive:
    src: "{{ uncompress_result.dest }}"
    dest: /opt/myapp/
    remote_src: true
  # Extracts all files from the tar to /opt/myapp/

- name: Step 3 - Clean up the intermediate tar file
  ansible.builtin.file:
    path: "{{ uncompress_result.dest }}"
    state: absent

Note: The two-pass approach is rarely needed. Use ansible.builtin.unarchive directly unless you have a specific reason to decompress and extract separately.

This collection uses Molecule for testing with Docker containers across multiple Ubuntu versions (22.04 and 24.04).

• Python 3.8 or later
• Docker (running daemon)
• Docker permissions for your user (or run tests as a user in the docker group)

1. Clone the repository:

   git clone https://github.com/compscidr/ansible-uncompress.git
   cd ansible-uncompress

2. Create and activate a Python virtual environment:

   # On Linux/macOS
   python3 -m venv venv
   source venv/bin/activate
   
   # On Windows
   python -m venv venv
   venv\Scripts\activate

3. Install test dependencies:

   pip install -r requirements.txt

4. Install required Ansible collections:

   ansible-galaxy collection install community.docker

Full test suite (recommended for CI/CD):

molecule test

This runs the complete test sequence:

• Syntax validation
• Container creation
• Dependency installation
• Test playbook execution
• Idempotence check
• Verification tests
• Cleanup and destruction

Development workflow (faster iteration):

molecule create     # Create test containers
molecule converge   # Run the test playbook
molecule verify     # Run verification tests
molecule destroy    # Clean up containers

Test a specific platform:

molecule test --platform-name ubuntu-22.04

Available platforms: ubuntu-22.04, ubuntu-24.04

Reset the test environment:

molecule destroy    # Clean up existing containers
molecule reset      # Clear configuration

The molecule tests validate:

• Downloading and uncompressing remote .gz files
• Uncompressing local .gz files with copy: true
• Uncompressing .bz2 files
• Uncompressing to directories with auto-derived filenames
• Handling .tar.gz files (strips .gz, keeps .tar)
• Correct dest return values for all scenarios
• File permissions are set correctly
• Decompressed file contents are valid
• Operations are idempotent (running twice produces the same result)

When done testing:

deactivate