PAR - Perl Archive Toolkit


This document describes version 0.69 of PAR, released May 31, 2003.


(If you want to make an executable that contains all module, scripts and data files, please consult pp instead.)

Following examples assume a foo.par file in Zip format; support for compressed tar (*.tgz/*.tbz2) format is under consideration.

To use from ./foo.par:

    % perl -MPAR=./foo.par -MHello
    % perl -MPAR=./foo -MHello          # the .par part is optional

Same thing, but search foo.par in the @INC;

    % perl -MPAR -Ifoo.par -MHello
    % perl -MPAR -Ifoo -MHello          # ditto

Following paths inside the PAR file are searched:

    /i386-freebsd/              # i.e. $Config{archname}
    /5.8.0/                     # i.e. $Config{version}
    /5.8.0/i386-freebsd/        # both of the above

Run script/ or from foo.par:

    % perl -MPAR foo.par        # only when $0 ends in '.par'

However, if the .par archive contains either script/ or, then it is used instead:

    % perl -MPAR foo.par        # runs, with '' as @ARGV

Use in a program:

    use PAR 'foo.par';
    use Hello; # reads within foo.par
    # PAR::read_file() returns a file inside any loaded PARs
    my $conf = PAR::read_file('data/MyConfig.yaml');
    # PAR::par_handle() returns an Archive::Zip handle
    my $zip = PAR::par_handle('foo.par')
    my $src = $zip->memberNamed('lib/')->contents;

You can also use wildcard characters:

    use PAR '/home/foo/*.par';  # loads all PAR files in that directory


This module lets you easily bundle a typical blib/ tree into a zip file, called a Perl Archive, or PAR.

It supports loading XS modules by overriding DynaLoader bootstrapping methods; it writes shared object file to a temporary file at the time it is needed.

To generate a .par file, all you have to do is compress the modules under arch/ and lib/, e.g.:

    % perl Makefile.PL
    % make
    % cd blib
    % zip -r mymodule.par arch/ lib/

Afterward, you can just use mymodule.par anywhere in your @INC, use PAR, and it will Just Work.

For maximal convenience, you can set the PERL5OPT environment variable to -MPAR to enable PAR processing globally (the overhead is small if not used), or to -MPAR=/path/to/mylib.par to load a specific PAR file. Alternatively, consider using the utility bundled with this module, or the self-contained parl utility on machines without installed.

Note that self-containing scripts and executables created with and pp may also be used as .par archives:

    % pp -o packed.exe        # generate packed.exe
    % perl -MPAR=packed.exe    # this also works
    % perl -MPAR -Ipacked.exe  # ditto

Please see /SYNOPSIS for most typical use cases.


In the next few releases, it is expected that the META.yml packed inside the PAR file will control the default behavior of temporary file creation, among other things; pp will also provide options to set those PAR-specific attributes. Currently, pp-generated PAR files will attach four such PAR-specific attributes in META.yml:

      cleartemp: 0      # default value of PAR_CLEARTEMP
      signature: ''     # key ID of the SIGNATURE file
      verbatim: 0       # were packed prerequisite's PODs preserved?
      version: x.xx     # version that generated this PAR

Additional attributes, like cipher and decrypt_key, are being discussed on the mailing list. Join us if you have an idea or two!


PAR::Intro, parl, pp

Archive::Zip, perlfunc/require

ex::lib::zip, Acme::use::strict::with::pride


Nicholas Clark for pointing out the mad source filter hook within the (also mad) coderef @INC hook, as well as (even madder) tricks one can play with PerlIO to avoid source filtering.

Ton Hospel for convincing me to ditch the Filter::Simple implementation.

Uri Guttman for suggesting read_file and par_handle interfaces.

Antti Lankila for making me implement the self-contained executable options via -O.

See the AUTHORS file in the distribution for a list of people who have sent helpful patches, ideas or comments.


Autrijus Tang <>

PAR has a mailing list, <>, that you can write to; send an empty mail to <> to join the list and participate in the discussion.

Please send bug reports to <>.


Copyright 2002, 2003 by Autrijus Tang <>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.