PAR(3)

📦

version 1.021 · 11 versions

💖 PAR 💖 — the Perl Archive Toolkit

okay so bestie, you found it: PAR(3), the User Contributed Perl Documentation page for the Perl Archive Toolkit. She's a whole vibe. Let's get into it 🦋

✨ SYNOPSIS ✨

(Real talk first: if you wanna make an executable that has all your modules, scripts and data files inside it, go look at the pp utility instead, okay? pp used to live inside the PAR distribution but now it ships as part of the PAR::Packer distribution instead. Not our problem anymore 💅)

The examples below are assuming you've got a foo.par file in Zip format. Slay.

To use Hello.pm from ./foo.par:

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

Same energy, but we search for foo.par in @INC:

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

The following paths inside the PAR file get searched:

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

PAR files can also (recursively, yes, recursively) contain other PAR files. Everything under these paths counts as a PAR file and gets searched too:

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

Wanna run script/test.pl or test.pl from foo.par?

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

BUT. If the .par archive contains either script/main.pl or main.pl, then that one gets used instead:

% perl -MPAR foo.par test.pl        # runs main.pl; @ARGV is 'test.pl'

Using it inside 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/Hello.pm')->contents;

You can use wildcard characters too, periodt:

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

Since version 0.950, there's also a different syntax for loading .par archives:

use PAR { file => 'foo.par' }, { file => 'otherfile.par' };

Why would you do that? Because you can also do this:

use PAR { file => 'foo.par, fallback => 1 };
use Foo::Bar;

Foo::Bar gets searched in the system libs first, and only loaded from foo.par if it wasn't found! the way that works… 🤌

use PAR { file => 'foo.par', run => 'myscript' };

This loads foo.par as usual and then executes the script/myscript file from the archive. Heads up: your program will not regain control. When script/myscript exits, so does your main program. To make this more useful you can defer it to runtime (otherwise equivalent):

require PAR;
PAR->import( { file => 'foo.par', run => 'myscript' } );

If you have PAR::Repository::Client installed, you can do this:

use PAR { repository => 'http://foo/bar/' };
use Module; # not locally installed!

And PAR will fetch any modules you don't have from the specified PAR repository. For the deets on how that works, peek at the SEE ALSO section below 👀. Instead of a URL or a local path, you can construct a PAR::Repository::Client object manually and hand that to PAR. If you specify the install => 1 option in the use PAR line above, the distribution containing Module will be permanently installed on your system. (use PAR { repository => 'http://foo/bar', install => 1 };)

Also there's an upgrade => 1 option that checks for upgrades in the repository in addition to installing. Please note that an upgraded version of a module is only loaded on the next run of your application.

Adding the dependencies => 1 option enables PAR::Repository::Client's static dependency resolution (that's PAR::Repository::Client 0.23 and up).

Finally — and this is iconic — you can combine the run and repository options to run an application directly from a repository! (And you can add the install option too.)

use PAR { repository => 'http://foo/bar/', run => 'my_app' };
# Will not reach this point as we executed my_app,

🌸 DESCRIPTION 🌸

This module lets you use special zip files, called Perl Archives, as libraries from which Perl modules can be loaded.

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

A .par file is mostly just a zip of the blib/ directory after the build process of a CPAN distribution. Wanna generate a .par yourself? All you have to do is compress the modules under arch/ and lib/, like:

% 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. Support for generating .par files is going to be in the next (beyond 0.2805) release of Module::Build.

For convenience, you can set the PERL5OPT environment variable to -MPAR to enable PAR processing globally (the overhead is small if not used); setting it to -MPAR=/path/to/mylib.par will load a specific PAR file. Alternatively, consider using the par.pl utility bundled with the PAR::Packer distribution, or using the self-contained parl utility which is also distributed with PAR::Packer on machines without PAR.pm installed. 🫶

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

% pp -o packed.exe source.pl        # generate packed.exe (see PAR::Packer)
% perl -MPAR=packed.exe other.pl    # this also works
% perl -MPAR -Ipacked.exe other.pl  # ditto

Please see SYNOPSIS for most typical use cases. 💅

🎀 NOTES 🎀

Settings in META.yml packed inside the PAR file may affect PAR's operation. For example, pp provides the -C (--clean) option to control the default behavior of temporary file creation.

Currently, pp-generated PAR files may attach four PAR-specific attributes in META.yml:

par:
  clean: 0          # default value of PAR_CLEAN
  signature: ''     # key ID of the SIGNATURE file
  verbatim: 0       # was packed prerequisite's PODs preserved?
  version: x.xx     # PAR.pm version that generated this PAR

User-defined environment variables, like PAR_GLOBAL_CLEAN, always override the ones set in META.yml. The algorithm for generating the caching/temporary directory goes like this:

If PAR_GLOBAL_TEMP is specified, use it as the cache directory for extracted libraries, and do not clean it up after execution.
If PAR_GLOBAL_TEMP is not set, but PAR_GLOBAL_CLEAN is specified, set PAR_GLOBAL_TEMP to TEMP/par-USERHEX/temp-PID/, cleaning it after execution.
If both are not set, use TEMP/par-USERHEX/cache-HASH/ as the PAR_GLOBAL_TEMP, reusing any existing files inside.

Here is a description of the variables in those previous paths 👇

TEMP is a temporary directory, which can be set via $ENV{PAR_GLOBAL_TMPDIR}, $ENV{TMPDIR}, $ENV{TEMPDIR}, $ENV{TEMP} or $ENV{TMP}, in that order of priority. If none of those are set, C:\TEMP, /tmp are checked. If neither of them exists, . is used.
USERHEX is derived from the user name, or SYSTEM if none can be found. On Win32, this is $Win32::LoginName. On Unix, this is $ENV{USERNAME} or $ENV{USER}. Encode the raw bytes of the user name each as two hex digits to obtain USERHEX.
PID is the process ID. Forked children use the parent's PID.
HASH is a crypto-hash of the entire par file or executable, calculated at creation time. This value can be overloaded with pp's --tempdir parameter.

By default, PAR strips POD sections from bundled modules. In case that causes trouble, you can turn this off by setting the environment variable PAR_VERBATIM to 1.

🦋 import options 🦋

When you use PAR {...} or call PAR->import({...}), the following options are available.

PAR->import({ file => 'foo.par' });
# or
PAR->import({ repository => 'http://foo/bar/' });

file — the par filename. You must pass one option of either 'file' or 'repository'.
repository — a par repository (exclusive of file).
fallback — search the system @INC before the par. Off by default for loading .par files via file => .... On by default for PAR repositories. To prefer loading modules from a repository over the locally installed modules, you can load the repository like this:

use PAR { repository => 'http://foo/bar/', fallback => 0 };

run — the name of a script to run in the par. Exits when done.
no_shlib_unpack — skip unpacking bundled dynamic libraries from shlib/$archname. The client may have them installed, or you may wish to cache them yourself. In either case, they must end up in the standard install location (such as /usr/local/lib/) or in $ENV{PAR_TEMP} before you require the module which needs them. If they are not accessible before you require the dependent module, perl will die with a message such as "cannot open shared object file..." 💀

🔥 SEE ALSO 🔥

PAR::Tutorial
The PAR::Packer distribution which contains the packaging utilities: par.pl, parl, pp.
PAR::Dist for details on PAR distributions.
PAR::Repository::Client for details on accessing PAR repositories. PAR::Repository for details on how to set up such a repository.
Archive::Zip, "require" in perlfunc
ex::lib::zip, Acme::use::strict::with::pride
Steffen Mueller has detailed slides on using PAR for application deployment at <http://steffen-mueller.net/talks/appdeployment/>.
PAR supports the prefork module. It declares various run-time dependencies so you can use the prefork module to get streamlined processes in a forking environment.

💜 ACKNOWLEDGMENTS 💜

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 par.pl -O.

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

💖 AUTHORS 💖

Okay so who made this whole thing? Say hi to the icons 👑

Audrey Tang — cpan@audreyt.org
Steffen Mueller — smueller@cpan.org

And bestie, you can literally just write to the mailing list at par@perl.org — or if you're feeling fancy, send an empty mail to par-subscribe@perl.org and boom, you're in the discussion 🫶 Archives of the mailing list are right here whenever you wanna lurk:

Bug reports? Please send those to https://github.com/rschupp/PAR/issues 🐛✨ But if what you actually need is support, then ngl the preferred move is joining the par@perl.org mailing list instead. iykyk 💅

📜 COPYRIGHT 📜

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

See LICENSE.

no cap, that's the legal bit and it matters — same terms as Perl itself, fr fr 🌸

And that's a wrap on the whole page, bestie 💖 This was PAR(3) from perl v5.42.0, dated 2025-08-04. Go forth and pack your Perl like the main character you are 👑🦋

📦 where this page comes from

fedora 43: perl-PAR 1.021-1.fc43 · 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