# perldoc > Archive::Extract

---
type: CommandReference
command: Archive::Extract
mode: perldoc
section: ""
source: perldoc
---

## Quick Reference
- `my $ae = Archive::Extract->new(archive => 'foo.tgz');` — create an extractor
- `$ae->extract;` — extract to current directory
- `$ae->extract(to => '/tmp');` — extract to a specific directory
- `$ae->extract or die $ae->error;` — extract and handle errors
- `my @files = @{ $ae->files };` — get list of files in the archive
- `my $extracted_to = $ae->extract_path;` — directory where files were extracted
- `$ae->is_tgz` — check if the archive is a tar.gz
- `$Archive::Extract::PREFER_BIN = 1;` — prefer command-line tools over Perl modules

## Name
Archive::Extract — A generic archive extracting mechanism

## Synopsis
perl
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;     # .tar
$ae->is_tgz;     # .tar.gz or .tgz
$ae->is_gz;      # .gz
$ae->is_zip;     # .zip, .jar, .par
$ae->is_bz2;     # .bz2
$ae->is_tbz;     # .tar.bz2 or .tbz
$ae->is_lzma;    # .lzma
$ae->is_xz;      # .xz
$ae->is_txz;     # .tar.xz or .txz

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

# paths to command-line tools, if found
$ae->bin_tar;
$ae->bin_gzip;
$ae->bin_unzip;
$ae->bin_bunzip2;
$ae->bin_unlzma;
$ae->bin_unxz;
## Methods
- `$ae = Archive::Extract->new(archive => $path, [type => $type])` — Creates an object. Automatically determines archive type from extension; override with `type`.
- `$ae->extract([to => $dir])` — Extracts archive to `$dir` (defaults to cwd). Returns true on success; sets `$ae->extract_path` and `$ae->files`.
- `$ae->error([$long])` — Returns last error string. Pass true for `Carp::longmess` output.
- `$ae->extract_path` — Directory where the archive was extracted.
- `$ae->files` — Array ref of relative paths of extracted files.
- `$ae->archive` — Full path to the archive file.
- `$ae->type` — The archive type string (e.g., `'tgz'`, `'zip'`).
- `$ae->types` — Returns a list of all known type strings.
- `$ae->is_tgz`, `$ae->is_tar`, `$ae->is_gz`, `$ae->is_Z`, `$ae->is_zip`, `$ae->is_bz2`, `$ae->is_tbz`, `$ae->is_lzma`, `$ae->is_xz`, `$ae->is_txz` — Boolean predicates for the archive type.
- `$ae->bin_tar`, `$ae->bin_gzip`, `$ae->bin_unzip`, `$ae->bin_bunzip2`, `$ae->bin_unlzma`, `$ae->bin_unxz` — Paths to system binaries, if found.
- `$ae->have_old_bunzip2` — Returns true if the installed bunzip2 requires `.bz2` suffix.
- `$ae->debug(MESSAGE)` — Outputs debug message if `$DEBUG` is true.
- `Archive::Extract::type_for($archive)` — Utility function that returns the type string for a filename based on its extension.
- `$Archive::Extract::DEBUG` — Set to true to print command-line tool output.
- `$Archive::Extract::WARN` — Set to false to suppress warnings (default true).
- `$Archive::Extract::PREFER_BIN` — Set to true to prefer command-line tools over Perl modules (default false).

## Examples
perl
# Specify type explicitly when the filename lacks a recognisable extension
use Archive::Extract;
my $ae = Archive::Extract->new(
    archive => '/tmp/02af6s',
    type    => Archive::Extract::type_for('archive.zip'),
);
$ae->extract or die $ae->error;
perl
# Prefer system binaries to reduce memory usage for large archives
$Archive::Extract::PREFER_BIN = 1;
my $ae = Archive::Extract->new(archive => 'huge.tar.gz');
$ae->extract(to => '/out') or die $ae->error;
## See Also
- [Archive::Tar](https://metacpan.org/pod/Archive::Tar)
- [Compress::Zlib](https://metacpan.org/pod/Compress::Zlib)
- [IO::Uncompress::Bunzip2](https://metacpan.org/pod/IO::Uncompress::Bunzip2)
- [IO::Uncompress::Unzip](https://metacpan.org/pod/IO::Uncompress::Unzip)