Archive::Extract(3)

📦

version 0.90 · 6 versions

0.90 · fedora 44 (latest)
0.88 · opensuse-leap 16.0
0.90 · arch rolling
0.88 · fedora 43
0.88 · fedora 44
0.88 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Archive::Extract — a generic archive extracting mechanism ✨

so like, this is the Archive::Extract(3) page, from the User Contributed Perl Documentation fam 🫶. if you've ever been like "bestie I just want to unzip ONE thing without learning nine different APIs", this module said bet.

🌸 SYNOPSIS 🌸

    use Archive::Extract;

    ### build an Archive::Extract object ###
    my $ae = Archive::Extract->new( archive => 'foo.tgz' );

    ### extract to cwd() ###
    my $ok = $ae->extract;

    ### extract to /tmp ###
    my $ok = $ae->extract( to => '/tmp' );

    ### what if something went wrong?
    my $ok = $ae->extract or die $ae->error;

    ### files from the archive ###
    my $files   = $ae->files;

    ### dir that was extracted to ###
    my $outdir  = $ae->extract_path;

    ### quick check methods ###
    $ae->is_tar     # is it a .tar file?
    $ae->is_tgz     # is it a .tar.gz or .tgz file?
    $ae->is_gz;     # is it a .gz file?
    $ae->is_zip;    # is it a .zip file?
    $ae->is_bz2;    # is it a .bz2 file?
    $ae->is_tbz;    # is it a .tar.bz2 or .tbz file?
    $ae->is_lzma;   # is it a .lzma file?
    $ae->is_xz;     # is it a .xz file?
    $ae->is_txz;    # is it a .tar.xz or .txz file?

    ### absolute path to the archive you provided ###
    $ae->archive;

    ### commandline tools, if found ###
    $ae->bin_tar     # path to /bin/tar, if found
    $ae->bin_gzip    # path to /bin/gzip, if found
    $ae->bin_unzip   # path to /bin/unzip, if found
    $ae->bin_bunzip2 # path to /bin/bunzip2 if found
    $ae->bin_unlzma  # path to /bin/unlzma if found
    $ae->bin_unxz    # path to /bin/unxz if found

🦋 DESCRIPTION 🦋

Archive::Extract is a generic archive extraction mechanism. periodt. 💅

the whole vibe is: it lets you extract any archive file of the type .tar, .tar.gz, .gz, .Z, tar.bz2, .tbz, .bz2, .zip, .xz, .txz, .tar.xz or .lzma — and you do not have to worry about how it does that, and you don't have to use a different interface for each type either. it handles it by using either perl modules, or commandline tools on your system. like, it just picks. iconic behavior honestly. 👑

if you want the deets on the picking, go peek at the "HOW IT WORKS" section further down. 🫶

🌈 METHODS 🌈

✨ `$ae = Archive::Extract->new(archive => '/path/to/archive',[type => TYPE])`

makes you a brand new Archive::Extract object, built off the archive file you handed it. it automatically figures out the type of archive from the extension — but you can override that by explicitly passing the type argument, maybe by calling type_for(). no cap, you have options. 💖

valid values for type are:

tar — standard tar files, as produced by, for example, /bin/tar. corresponds to a .tar suffix.
tgz — gzip compressed tar files, as produced by, for example /bin/tar -z. corresponds to a .tgz or .tar.gz suffix.
gz — gzip compressed file, as produced by, for example /bin/gzip. corresponds to a .gz suffix.
Z — Lempel-Ziv compressed file, as produced by, for example /bin/compress. corresponds to a .Z suffix.
zip — zip compressed file, as produced by, for example /bin/zip. corresponds to a .zip, .jar or .par suffix.
bz2 — bzip2 compressed file, as produced by, for example, /bin/bzip2. corresponds to a .bz2 suffix.
tbz — bzip2 compressed tar file, as produced by, for example /bin/tar -j. corresponds to a .tbz or .tar.bz2 suffix.
lzma — lzma compressed file, as produced by /bin/lzma. corresponds to a .lzma suffix.
xz — xz compressed file, as produced by /bin/xz. corresponds to a .xz suffix.
txz — xz compressed tar file, as produced by, for example /bin/tar -J. corresponds to a .txz or .tar.xz suffix.

returns an Archive::Extract object on success, or false on failure. 😭 (we've all been there)

✨ `$ae->extract( [to => '/output/path'] )`

extracts the archive that your Archive::Extract object represents, and drops it wherever you want — you tell it where with the to argument. it defaults to cwd(). ✨

now listen, this part matters: since .gz files never hold a directory, but only a single file — if the to argument is an existing directory, the file is extracted there, with its .gz suffix stripped. if the to argument is not an existing directory, then the to argument is understood to be a filename, if the archive type is gz. and in the case that you did not specify a to argument at all, the output file will be the name of the archive file, stripped from its .gz suffix, in the current working directory. ok bestie? ok. 🫶

extract will try a pure perl solution first, and then fall back to commandline tools if they are available. want to flip that order? see the "GLOBAL VARIABLES" section below, it's right there. 👀

it returns true on success, and false on failure.

on success, it will also set the following attributes in the object:

$ae->extract_path — this is the directory that the files where extracted to.
$ae->files — this is an array ref with the paths of all the files in the archive, relative to the to argument you specified. to get the full path to an extracted file, you would use:

    File::Spec->catfile( $to, $ae->files->[0] );

note that all files from a tar archive will be in unix format, as per the tar specification. 🐧

💅 ACCESSORS 💅

`$ae->error([BOOL])`

returns the last encountered error as string. pass it a true value to get the Carp::longmess() output instead. (the long one. the dramatic one. 💀)

`$ae->extract_path`

this is the directory the archive got extracted to. see extract() for details.

`$ae->files`

this is an array ref holding all the paths from the archive. see extract() for details.

`$ae->archive`

this is the full path to the archive file represented by this Archive::Extract object.

`$ae->type`

this is the type of archive represented by this Archive::Extract object. see the accessors below for an easier way to use this. see the new() method for details.

`$ae->types`

returns a list of all known types for Archive::Extract's new method. 📋

`$ae->is_tgz`

returns true if the file is of type .tar.gz. see the new() method for details.

`$ae->is_tar`

returns true if the file is of type .tar. see the new() method for details.

`$ae->is_gz`

returns true if the file is of type .gz. see the new() method for details.

`$ae->is_Z`

returns true if the file is of type .Z. see the new() method for details.

`$ae->is_zip`

returns true if the file is of type .zip. see the new() method for details.

`$ae->is_lzma`

returns true if the file is of type .lzma. see the new() method for details.

`$ae->is_xz`

returns true if the file is of type .xz. see the new() method for details.

`$ae->bin_tar`

returns the full path to your tar binary, if found. 🔍

`$ae->bin_gzip`

returns the full path to your gzip binary, if found

`$ae->bin_unzip`

returns the full path to your unzip binary, if found

`$ae->bin_unlzma`

returns the full path to your unlzma binary, if found

`$ae->bin_unxz`

returns the full path to your unxz binary, if found

`$bool = $ae->have_old_bunzip2`

older versions of /bin/bunzip2, from before the bunzip2 1.0 release, require all archive names to end in .bz2 or it will not extract them. 😤 this method checks if you have a recent version of bunzip2 that allows any extension, or an older one that doesn't.

`debug( MESSAGE )`

this method outputs MESSAGE to the default filehandle if $DEBUG is true. it's a small method, but it's here if you'd like to subclass it so you can so something else with any debugging output. 🐛

🧚 UTILITY FUNCTION 🧚

`type_for($archive)`

given an archive file name, it determins the type by parsing the file name extension. used by new() when the type parameter is not passed. also useful when the archive file does not include a suffix but the file name is otherwise known, such as when a file is uploaded to a web server and stored with a temporary name that differs from the original name, and you want to use the same detection pattern as Archive::Extract. example:

    my $ae = Archive::Extract->new(
        archive => '/tmp/02af6s',
        type    => Archive::Extract::type_for('archive.zip'),
    );

⭐ HOW IT WORKS ⭐

Archive::Extract tries first to determine what type of archive you are passing it, by inspecting its suffix. it does not do this by using Mime magic, or something related. see "CAVEATS" below. 🔮

once it has determined the file type, it knows which extraction methods it can use on the archive. it will try a perl solution first, then fall back to a commandline tool if that fails. and if that also fails, it will return false, indicating it was unable to extract the archive. 😭 see the section on "GLOBAL VARIABLES" to see how to alter this order.

👑 CAVEATS 👑

🌸 File Extensions

Archive::Extract trusts on the extension of the archive to determine what type it is, and what extractor methods therefore can be used. if your archives do not have any of the extensions as described in the new() method, you will have to specify the type explicitly, or Archive::Extract will not be able to extract the archive for you. so like, name your files correctly bestie. 💅

🌸 Supporting Very Large Files

Archive::Extract can use either pure perl modules or command line programs under the hood. some of the pure perl modules (like Archive::Tar and Compress::unLZMA) take the entire contents of the archive into memory, which may not be feasible on your system. consider setting the global variable $Archive::Extract::PREFER_BIN to 1, which will prefer the use of command line programs and won't consume so much memory. 🧠✨

see the "GLOBAL VARIABLES" section below for details.

🌸 Bunzip2 support of arbitrary extensions.

older versions of /bin/bunzip2 do not support arbitrary file extensions and insist on a .bz2 suffix. although we do our best to guard against this, if you experience a bunzip2 error, it may be related to this. for details, please see the have_old_bunzip2 method.

💜 GLOBAL VARIABLES 💜

`$Archive::Extract::DEBUG`

set this variable to true to have all calls to command line tools be printed out, including all their output. this also enables Carp::longmess errors, instead of the regular carp errors.

good for tracking down why things don't work with your particular setup. 🕵️

defaults to false.

`$Archive::Extract::WARN`

this variable controls whether errors encountered internally by Archive::Extract should be carp'd or not.

set to false to silence warnings. inspect the output of the error() method manually to see what went wrong. 🤫

defaults to true.

`$Archive::Extract::PREFER_BIN`

this variables controls whether Archive::Extract should prefer the use of perl modules, or commandline tools to extract archives.

set to true to have Archive::Extract prefer commandline tools.

defaults to false.

💀 TODO / CAVEATS 💀

okay bestie, this is the part where we're honest about the flaws ✨ because every icon has lore, and this module's lore includes a couple of "yeahhh we know" moments. ngl, read these before you get mad at it 💅

🔮 Mime magic support

so like… maybe this module should use something like File::Type to figure out the type, instead of just blindly trusting the suffix? 🙈 that's the vibe here. it's giving "trust fall with a file extension," and file extensions are NOT always honest, fr fr.

🧵 Thread safety

lowkey important: right now, Archive::Extract does a chdir to the extraction dir before extraction, and a chdir back again after. which means it is not necessarily thread safe 😭 bestie please note that. see rt.cpan.org bug #45671 for the full tea.

🫶 so if you're threading, be careful. this is a real caveat, not a drill.

🐛 BUG REPORTS 🐛

found a bug? got an issue? don't suffer in silence, bestie 💖 please report bugs or other issues to <bug-archive-extract@rt.cpan.org>.

👑 AUTHOR 👑

this module by Jos Boumans <kane@cpan.org>. king behaviour, no cap 👑

📜 COPYRIGHT 📜

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself. 🎀 slay, that's the whole legal bit, and yes it's iconic.

okay that's the entire page, bestie, we made it to the end together 🦋✨ this whole thing was for perl v5.42.3, dated 2026-08-25 — so if you're reading this way later, hi from the past, hope your extractions are flawless 💜🌸

📦 where this page comes from

fedora 44: perl-Archive-Extract 1:0.90-1.fc44 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Archive::Extract(3)

💖 NAME 💖

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🌈 METHODS 🌈

✨ $ae = Archive::Extract->new(archive => '/path/to/archive',[type => TYPE])

✨ $ae->extract( [to => '/output/path'] )

💅 ACCESSORS 💅

$ae->error([BOOL])

$ae->extract_path

$ae->files

$ae->archive

$ae->type

$ae->types

$ae->is_tgz

$ae->is_tar

$ae->is_gz

$ae->is_Z

$ae->is_zip

$ae->is_lzma

$ae->is_xz

$ae->bin_tar

$ae->bin_gzip

$ae->bin_unzip

$ae->bin_unlzma

$ae->bin_unxz

$bool = $ae->have_old_bunzip2

debug( MESSAGE )