# man > Archive::Extract(3pm)

---
type: CommandReference
command: Archive::Extract
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference
- `my $ae = Archive::Extract->new(archive => 'file.tar.gz')` — create extractor for a tarball
- `$ae->extract` or `$ae->extract(to => '/tmp')` — extract archive to current (default) or specified directory
- `$ae->extract or die $ae->error` — extract and check for errors
- `my @files = @{ $ae->files }` — get list of extracted files (relative to `to`)
- `my $out = $ae->extract_path` — get the directory where archive was extracted
- `$ae->is_tgz`, `$ae->is_zip`, `$ae->is_txz`, etc. — test archive type
- `my $type = Archive::Extract::type_for('backup.zip')` — determine type from filename extension

## Name
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 current working directory
my $ok = $ae->extract;

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

# Handle error
my $ok = $ae->extract or die $ae->error;

# Inspect results
my $files  = $ae->files;
my $outdir = $ae->extract_path;

# Quick type checks
$ae->is_tar;     $ae->is_tgz;     $ae->is_gz;      $ae->is_zip;
$ae->is_bz2;     $ae->is_tbz;     $ae->is_lzma;    $ae->is_xz;
$ae->is_txz;

# Locations of external tools, if found
$ae->bin_tar;     $ae->bin_gzip;    $ae->bin_unzip;
$ae->bin_bunzip2; $ae->bin_unlzma;  $ae->bin_unxz;
## Options

### Constructor

- `$ae = Archive::Extract->new(archive => '/path/to/archive', [type => TYPE])`  
  Creates an `Archive::Extract` object. The archive type is auto‑detected by extension; override with the `type` argument (valid values: `tar`, `tgz`, `gz`, `Z`, `zip`, `bz2`, `tbz`, `lzma`, `xz`, `txz`). Returns the object on success, false on failure.

### Extraction

- `$ae->extract( [to => '/output/path'] )`  
  Extracts the archive to the given directory (default `cwd()`). For `.gz` files (which contain a single file), if `to` is an existing directory the file is placed there **without** the `.gz` extension; if `to` is not a directory it is used as the filename.  
  On success, sets `$ae->extract_path` and `$ae->files`.  
  Returns true on success, false on failure.

### Accessors

Provides these read‑only attributes:

- **`$ae->error([BOOL])`** — last error string. Pass a true value to get a `Carp::longmess` stack trace.
- **`$ae->extract_path`** — directory the archive was extracted to.
- **`$ae->files`** — arrayref of file paths *relative* to the extraction destination.
- **`$ae->archive`** — full path to the archive file.
- **`$ae->type`** — archive type string (e.g. `'tgz'`).

Type‑checking methods (each returns true if the archive matches):

- `$ae->is_tar`, `$ae->is_tgz`, `$ae->is_gz`, `$ae->is_Z`, `$ae->is_zip`, `$ae->is_bz2`, `$ae->is_tbz`, `$ae->is_lzma`, `$ae->is_xz`, `$ae->is_txz`

External tool paths (set if the binaries were found):

- `$ae->bin_tar`, `$ae->bin_gzip`, `$ae->bin_unzip`, `$ae->bin_bunzip2`, `$ae->bin_unlzma`, `$ae->bin_unxz`

Miscellaneous:

- `$ae->types` — list of all known archive type strings.
- `$ae->have_old_bunzip2` — returns true if the system `bunzip2` is older than 1.0 and requires `.bz2` extension.
- `$ae->debug( MESSAGE )` — prints `MESSAGE` to the default filehandle if `$DEBUG` is true.

### Utility Function

- `Archive::Extract::type_for($archive)`  
  Determines the archive type from the file extension. Used internally by `new()` when `type` is omitted. Also usable when the actual file name differs (e.g. temp uploads):
  ```perl
  my $ae = Archive::Extract->new(
      archive => '/tmp/02af6s',
      type    => Archive::Extract::type_for('archive.zip'),
  );
  
### Global Variables

- **`$Archive::Extract::DEBUG`** — set true to print every command and its output. Also activates `Carp::longmess` errors. Default false.
- **`$Archive::Extract::WARN`** — set false to silence internal `carp` warnings. Check `$ae->error` manually. Default true.
- **`$Archive::Extract::PREFER_BIN`** — set true to prefer command‑line tools over pure‑Perl modules. Useful to avoid high memory usage with large archives. Default false.

## Examples
perl
use Archive::Extract;

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

# Extract to current working directory
my $ok = $ae->extract;

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

# Handle error
my $ok = $ae->extract or die $ae->error;

# Inspect results
my $files  = $ae->files;
my $outdir = $ae->extract_path;

# Quick type checks
$ae->is_tar;     $ae->is_tgz;     $ae->is_gz;      $ae->is_zip;
$ae->is_bz2;     $ae->is_tbz;     $ae->is_lzma;    $ae->is_xz;
$ae->is_txz;

# Locations of external tools, if found
$ae->bin_tar;     $ae->bin_gzip;    $ae->bin_unzip;
$ae->bin_bunzip2; $ae->bin_unlzma;  $ae->bin_unxz;
## See Also

- [Archive::Tar](http://localhost/phpMan.php/perldoc/Archive%3A%3ATar/markdown)
- [Compress::unLZMA](http://localhost/phpMan.php/perldoc/Compress%3A%3AunLZMA/markdown)
- [File::Spec](http://localhost/phpMan.php/perldoc/File%3A%3ASpec/markdown)
- [Carp](http://localhost/phpMan.php/perldoc/Carp/markdown)
- [File::Type](http://localhost/phpMan.php/perldoc/File%3A%3AType/markdown)