Skip to main content

Unarchive

Extracts all files from an archive to the target directory. Supports various archive formats including password-protected RAR archives.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Source Path - Path to the archive file to extract. Supports Zip, Tar, TarGz, TarBz2, TarXz, RAR, and other archive formats.

  • Target Path - Destination directory where all files will be extracted. The directory structure from the archive will be preserved.

Options​

  • Rar Password - Password for password-protected RAR archives. Only applicable when extracting RAR files. Leave empty for non-password-protected archives.

How It Works​

The Unarchive node performs complete archive extraction:

  1. Opens the archive file at the specified path
  2. Checks if the archive is password-protected (RAR files)
  3. If a RAR password is provided, uses it for extraction
  4. Reads all files and directory structure from the archive
  5. Extracts all content to the target directory
  6. Preserves the original directory structure and file attributes

The extraction process maintains the complete directory hierarchy as it exists in the archive.

Supported Archive Formats​

  • Zip (.zip) - Standard Zip archives
  • Tar (.tar) - Uncompressed tar archives
  • TarGz (.tar.gz, .tgz) - Gzip compressed tar archives
  • TarBz2 (.tar.bz2) - Bzip2 compressed tar archives
  • TarXz (.tar.xz) - XZ compressed tar archives
  • TarZstd (.tar.zst) - Zstandard compressed tar archives
  • TarLz4 (.tar.lz4) - LZ4 compressed tar archives
  • RAR (.rar) - RAR archives (including password-protected)
  • 7z (.7z) - 7-Zip archives

Examples​

Example 1: Extract a Zip Archive​

Extract all files from a Zip archive:

// Set archive and extraction paths
msg.archiveFile = "/home/user/downloads/project.zip";
msg.extractPath = "/home/user/projects/extracted/";

Configure the Unarchive node:

  • Source Path: {{msg.archiveFile}}
  • Target Path: {{msg.extractPath}}

Example 2: Extract TarGz Archive​

Extract a compressed tar archive:

// Extract tar.gz backup
msg.backupFile = "/home/user/backups/data-backup.tar.gz";
msg.restorePath = "/home/user/restore/";

Configure the Unarchive node:

  • Source Path: {{msg.backupFile}}
  • Target Path: {{msg.restorePath}}

Example 3: Extract Password-Protected RAR​

Extract a password-protected RAR archive:

// Set paths for RAR extraction
msg.rarFile = "/home/user/downloads/confidential.rar";
msg.outputPath = "/home/user/confidential/";

Configure the Unarchive node:

  • Source Path: {{msg.rarFile}}
  • Target Path: {{msg.outputPath}}
  • Rar Password: Store the password in Vault and reference it

Example 4: Extract with Directory Creation​

Extract to a new directory that doesn't exist yet:

const fs = require('fs');
const path = require('path');

// Define paths
msg.archivePath = "/home/user/downloads/release-v2.0.zip";
msg.extractDir = "/home/user/releases/v2.0/";

// Create target directory if it doesn't exist
if (!fs.existsSync(msg.extractDir)) {
    fs.mkdirSync(msg.extractDir, { recursive: true });
    console.log("Created extraction directory:", msg.extractDir);
}

Configure the Unarchive node:

  • Source Path: {{msg.archivePath}}
  • Target Path: {{msg.extractDir}}

Example 5: Extract and Verify Contents​

Extract archive and verify all files were extracted:

// Set extraction parameters
msg.sourceArchive = "/home/user/backups/documents.zip";
msg.targetDir = "/home/user/documents/restored/";

Configure the Unarchive node:

  • Source Path: {{msg.sourceArchive}}
  • Target Path: {{msg.targetDir}}

Add a Function node after extraction to verify:

const fs = require('fs');
const path = require('path');

// Count extracted files
function countFiles(dir) {
    let count = 0;
    const items = fs.readdirSync(dir);

    items.forEach(item => {
        const fullPath = path.join(dir, item);
        const stats = fs.statSync(fullPath);

        if (stats.isDirectory()) {
            count += countFiles(fullPath);
        } else {
            count++;
        }
    });

    return count;
}

msg.extractedFileCount = countFiles(msg.targetDir);
msg.message = `Extracted ${msg.extractedFileCount} files to ${msg.targetDir}`;
console.log(msg.message);

Example 6: Batch Archive Extraction​

Extract multiple archives in sequence:

// Define archives to extract
msg.archives = [
    {
        source: "/home/user/downloads/archive1.zip",
        target: "/home/user/extracted/archive1/"
    },
    {
        source: "/home/user/downloads/archive2.tar.gz",
        target: "/home/user/extracted/archive2/"
    },
    {
        source: "/home/user/downloads/archive3.7z",
        target: "/home/user/extracted/archive3/"
    }
];

// Initialize processing
msg.currentIndex = 0;
msg.currentArchive = msg.archives[msg.currentIndex];

Configure the Unarchive node:

  • Source Path: {{msg.currentArchive.source}}
  • Target Path: {{msg.currentArchive.target}}

Use a Loop to process all archives.

Example 7: Extract with Cleanup​

Extract archive and optionally delete it after extraction:

// Set paths
msg.archiveFile = "/home/user/temp/download.zip";
msg.extractPath = "/home/user/data/";
msg.deleteAfterExtract = true;

Configure the Unarchive node:

  • Source Path: {{msg.archiveFile}}
  • Target Path: {{msg.extractPath}}

Add a Function node after extraction:

const fs = require('fs');

if (msg.deleteAfterExtract) {
    try {
        fs.unlinkSync(msg.archiveFile);
        msg.message = "Archive extracted and deleted successfully";
        console.log(msg.message);
    } catch (error) {
        msg.message = "Archive extracted but could not be deleted: " + error.message;
        console.error(msg.message);
    }
} else {
    msg.message = "Archive extracted successfully";
}

Example 8: Conditional Extraction Based on Archive Size​

Check archive size before extracting:

const fs = require('fs');

msg.archivePath = "/home/user/downloads/large-archive.zip";
msg.extractPath = "/home/user/data/";

// Check archive size
const stats = fs.statSync(msg.archivePath);
const sizeInMB = stats.size / (1024 * 1024);

msg.archiveSizeMB = sizeInMB.toFixed(2);
msg.shouldExtract = sizeInMB < 1000; // Only extract if less than 1GB

if (msg.shouldExtract) {
    msg.message = `Archive size: ${msg.archiveSizeMB}MB - proceeding with extraction`;
} else {
    msg.message = `Archive size: ${msg.archiveSizeMB}MB - too large, skipping extraction`;
}

console.log(msg.message);

Use a Decision node to conditionally execute the Unarchive node based on msg.shouldExtract.

Usage Tips​

  1. Target Directory:

    • The target directory should exist before extraction
    • Use File System nodes to create directories if needed
    • The archive's internal directory structure will be preserved

  2. Password Protection:

    • RAR password protection is supported
    • Store passwords securely in Vault credentials
    • Other archive formats may not support password protection

  3. Disk Space:

    • Ensure sufficient disk space for extracted content
    • Archives can expand significantly (5-10x or more)
    • Check available space before extracting large archives

  4. Performance:

    • Large archives take time to extract
    • Consider using Continue On Error for partial extractions
    • Monitor extraction progress for very large archives

  5. Archive Format Detection:

    • Format is automatically detected from file extension and content
    • No need to specify the archive type
    • Handles multiple compression formats automatically

  6. File Overwriting:

    • Existing files in the target directory may be overwritten
    • Backup important files before extracting to existing directories
    • Use unique target directories for each extraction

Common Errors and Solutions​

Error: "Source path cannot be empty"​

Cause: The Source Path input is not provided or is empty.

Solution: Ensure you provide a valid path to the archive file.

Error: "Source path does not exist"​

Cause: The specified archive file does not exist at the given path.

Solution:

  • Verify the archive path is correct
  • Check that the file exists and hasn't been moved or deleted
  • Ensure proper path formatting
  • Confirm the file download completed if from external source

Error: "Target path cannot be empty"​

Cause: The Target Path input is not provided or is empty.

Solution: Provide a valid destination directory path for extraction.

Error: Target directory does not exist​

Cause: The target directory doesn't exist and cannot be created.

Solution:

  • Create the target directory before running the node
  • Use File System nodes to create the directory structure
  • Ensure parent directories exist

Error: Corrupted archive​

Cause: The archive file is corrupted or incomplete.

Solution:

  • Verify the archive with standard tools
  • Re-download the archive if it was downloaded
  • Check if the archive creation process completed successfully
  • Ensure the file wasn't truncated during transfer

Error: Invalid password for RAR archive​

Cause: The password provided is incorrect or the archive is not password-protected.

Solution:

  • Verify the password is correct
  • Check if the RAR file is actually password-protected
  • Ensure the password is properly configured in Vault
  • Try extracting without password if archive is not protected

Error: Unsupported archive format​

Cause: The archive format is not supported.

Solution:

  • Check the file extension matches a supported format
  • Verify the file is actually an archive (not just renamed)
  • Convert to a supported format if possible
  • Use appropriate tools for exotic archive formats

Error: Permission denied​

Cause: Insufficient permissions to read the archive or write to the target directory.

Solution:

  • Ensure read permissions for the archive file
  • Verify write permissions for the target directory
  • Check directory ownership and permissions
  • Run with appropriate user permissions

Error: Disk space insufficient​

Cause: Not enough disk space to extract the archive contents.

Solution:

  • Free up disk space on the target drive
  • Choose a different target location with more available space
  • Extract to a larger drive or network storage
  • Remove unnecessary files before extraction

Error: File already exists​

Cause: Files in the archive conflict with existing files in the target directory.

Solution:

  • Clear the target directory before extraction
  • Use a different target directory
  • Backup existing files if needed
  • Accept that files will be overwritten if this is expected
  • Archive - Create archives from multiple files
  • Extract File - Extract specific files instead of entire archive
  • Inspect Archive File - View archive contents before extraction
  • Decompress - Decompress single compressed files
    • Compress files and folders