pp(3pm)

pp(3pm) 💖 PAR Packager 🎀

User Contributed Perl Documentation

---

✨ NAME ✨

• pp — PAR Packager 💅

🌸 SYNOPSIS 🌸

pp [ -ABCEFILMPTSVXacdefghilmnoprsuvxz ] [ parfile | scriptfile ]...

🦋 EXAMPLES 🦋

Note: When running on Microsoft Windows, the a.out below will be replaced by a.exe instead.

% pp hello.pl               # Pack 'hello.pl' into executable 'a.out'
% pp -o hello hello.pl      # Pack 'hello.pl' into executable 'hello'
                            # (or 'hello.exe' on Win32)

% pp -o foo foo.pl bar.pl   # Pack 'foo.pl' and 'bar.pl' into 'foo'
% ./foo                     # Run 'foo.pl' inside 'foo'
% mv foo bar; ./bar         # Run 'bar.pl' inside 'foo'
% mv bar baz; ./baz         # Error: Can't open perl script "baz"

% pp -p file                # Creates a PAR file, 'a.par'
% pp -o hello a.par         # Pack 'a.par' to executable 'hello'
% pp -S -o hello file       # Combine the two steps above

% pp -p -o out.par file     # Creates 'out.par' from 'file'
% pp -B -p -o out.par file  # same as above, but bundles core modules
                            # and removes any local paths from @INC
% pp -P -o out.pl file      # Creates 'out.pl' from 'file'
% pp -B -p -o out.pl file   # same as above, but bundles core modules
                            # and removes any local paths from @INC
                            # (-B is assumed when making executables)

% pp -e "print 123"         # Pack a one-liner into 'a.out'
% pp -p -e "print 123"      # Creates a PAR file 'a.par'
% pp -P -e "print 123"      # Creates a perl script 'a.pl'

% pp -c hello               # Check dependencies from "perl -c hello"
% pp -x hello               # Check dependencies from "perl hello"
% pp -n -x hello            # same as above, but skips static scanning

% pp -I /foo hello          # Extra include paths
% pp -M Foo::Bar hello      # Extra modules in the include path
% pp -M abbrev.pl hello     # Extra libraries in the include path
% pp -X Foo::Bar hello      # Exclude modules
% pp -a data.txt hello      # Additional data files

% pp -r hello               # Pack 'hello' into 'a.out', runs 'a.out'
% pp -r hello a b c         # Pack 'hello' into 'a.out', runs 'a.out'
                            # with arguments 'a b c'

% pp hello --log=c          # Pack 'hello' into 'a.out', logs
                            # messages into 'c'

# Pack 'hello' into a console-less 'out.exe' (Win32 only)
% pp --gui -o out.exe hello

% pp @file hello.pl         # Pack 'hello.pl' but read _additional_
                            # options from file 'file'

🌈 DESCRIPTION 🌈

Okay so pp creates standalone executables from Perl programs, using the compressed packager provided by PAR, and dependency detection heuristics offered by Module::ScanDeps. Source files are compressed verbatim without compilation. ✨

You may think of pp as "perlcc that works without hassle". :-)

A GUI interface is also available as the tkpp command. slay.

It does not provide the compilation-step acceleration provided by perlcc (however, see -f below for byte-compiled, source-hiding techniques), but makes up for it with better reliability, smaller executable size, and full retrieval of original source code. iconic behavior.

When a single input program is specified, the resulting executable will behave identically as that program. However, when multiple programs are packaged, the produced executable will run the one that has the same basename as $0 (i.e. the filename used to invoke it). If nothing matches, it dies with the error "Can't open perl script "$0"". 💀

💅 OPTIONS 💅

Options are available in a short form and a long form. For example, the three lines below are all equivalent:

% pp -o output.exe input.pl
% pp --output output.exe input.pl
% pp --output=output.exe input.pl

Since the command lines can become sufficiently long to reach the limits imposed by some shells, it is possible to have pp read some of its options from one or more text files. The basic usage is to just include an argument starting with an 'at' (@) sigil. This argument will be interpreted as a file to read options from. Mixing ordinary options and @file options is possible. This is implemented using the Getopt::ArgvFile module, so read its documentation for advanced usage. Note that Getopt::ArgvFile is used here with parameter "resolveEnvVars=1", i.e. substrings of the form ${FOO"}" in the contents of @file are replaced with the value of environment variable FOO. 🫶

• -a, --addfile=FILE|DIR — Add an extra file into the package. If the file is a directory, recursively add all files inside that directory, with links turned into actual files. 🎀

By default, files are placed under "/" inside the package with their original names. You may override this by appending the target filename after a ";", like this:

% pp -a "old_filename.txt;new_filename.txt"
% pp -a "old_dirname;new_dirname"

You may specify "-a" multiple times.

• -A, --addlist=FILE — Read a list of file/directory names from FILE, adding them into the package. Each line in FILE is taken as an argument to -a above.

You may specify "-A" multiple times. 💖

• -B, --bundle — Bundle core modules in the resulting package. This option is enabled by default, except when "-p" or "-P" is specified.

Since PAR version 0.953, this also strips any local paths from the list of module search paths @INC before running the contained script. 🔥

• -C, --clean — Clean up temporary files extracted from the application at runtime. By default, these files are cached in the temporary directory; this allows the program to start up faster next time. ✨
• -c, --compile — Run "perl -c inputfile" to determine additional run-time dependencies.
• -cd, --cachedeps=FILE — Use FILE to cache detected dependencies. Creates FILE unless present. This will speed up the scanning process on subsequent runs. 💅
• -d, --dependent — Reduce the executable size by not including a copy of perl interpreter. Executables built this way will need a separate perl5x.dll or libperl.so to function correctly. This option is only available if perl is built as a shared library.
• -e, --eval=STRING — Package a one-liner, much the same as "perl -e '...'"
• -E, --evalfeature=STRING — Behaves just like -e, except that it implicitly enables all optional features (in the main compilation unit) with Perl 5.10 and later. See feature. 🦋
• -x, --execute — Run "perl inputfile" to determine additional run-time dependencies.

Using this option, pp may be able to detect the use of modules that can't be determined by static analysis of "inputfile". Examples are stuff loaded by run-time loaders like Module::Runtime or "plugin" loaders like Module::Loader. Note that which modules are detected depends on which parts of your program are exercised when running "inputfile". E.g. if your program immediately terminates when run as "perl inputfile" because it lacks mandatory arguments, then this option will probably have no effect. You may use --xargs to supply arguments in this case.

• --xargs=STRING — If -x is given, splits the "STRING" using the function "shellwords" from Text::ParseWords and passes the result as @ARGV when running "perl inputfile". 🌸
• -X, --exclude=MODULE — Exclude the given module from the dependency search path and from the package. If the given file is a zip or par or par executable, all the files in the given file (except MANIFEST, META.yml and script/*) will be excluded and the output file will "use" the given file at runtime. 🔥
• -f, --filter=FILTER — Filter source script(s) with a PAR::Filter subclass. You may specify multiple such filters.

If you wish to hide the source code from casual prying, this will do:

% pp -f Bleach source.pl

If you are more serious about hiding your source code, you should have a look at Steve Hay's PAR::Filter::Crypto module. Make sure you understand the Filter::Crypto caveats!

Note: Most filters are incompatible with "__DATA__" sections in your source. The packed executable typically aborts with an error message like

readline() on unopened filehandle DATA at (eval 13) line 3.

• -g, --gui — Build an executable that does not have a console window. This option is ignored on non-MSWin32 platforms or when "-p" is specified. 🎀
• -h, --help — Show basic usage information.
• -I, --lib=DIR — Add the given directory to the perl module search path. May be specified multiple times.
• -l, --link=FILE|LIBRARY — Add the given shared library (a.k.a. shared object or DLL) into the packed file. Also accepts names under library paths; i.e. "-l ncurses" means the same thing as "-l libncurses.so" or "-l /usr/local/lib/libncurses.so" in most Unixes. May be specified multiple times.
• -L, --log=FILE — Log the output of packaging to a file rather than to stdout.
• -F, --modfilter=FILTER[=REGEX], — Filter included perl module(s) with a PAR::Filter subclass. You may specify multiple such filters.

By default, the PodStrip filter is applied. In case that causes trouble, you can turn this off by setting the environment variable "PAR_VERBATIM" to 1.

Since PAR 0.958, you can use an optional regular expression (REGEX above) to select the files in the archive which should be filtered. The regular expression is matched against module names as they would appear as keys in %INC, e.g. "Foo/Bar.pm" for module "Foo::Bar". Examples:

pp -o foo.exe -F 'Bleach=warnings\.pm$' foo.pl

This creates a binary executable foo.exe from foo.pl packaging all files as usual except for files ending in "warnings.pm" which are filtered with PAR::Filter::Bleach.

pp -o foo.exe -F 'Bleach=^(?!Win32/)' foo.pl

This "bleaches" all modules except those in the "Win32::" namespace.

Note: The same restriction on "__DATA__" sections holds as for --filter.

• -M, --module=MODULE — Add the specified module into the package, along with its dependencies.

The following variants may be used to add whole module namespaces:

• -M Foo::** — Add every module in the "Foo" namespace except "Foo" itself, i.e. add "Foo::Bar", "Foo::Bar::Quux" etc up to any depth.
• -M Foo::* — Add every module at level 1 in the "Foo" namespace, i.e. add "Foo::Bar", but neither "Foo::Bar::Quux" nor "Foo".

• -M Foo:: — shorthand for -M Foo -M Foo:**: literally every module in the Foo namespace, Foo itself included. no modules left behind bestie 💫
• Okay plot twist: instead of a module name, MODULE can also be a filename relative to the @INC path. So -M Module/ScanDeps.pm means exactly the same thing as -M Module::ScanDeps. iconic, right?? 😌
• If MODULE has an extension that is not .pm/.ix/.al, it will not be scanned for dependencies at all, and it gets placed under / instead of /lib/ inside the PAR file. ⚠️ And listen — this use is deprecated — consider using the -a option instead. the more you know 🌈
• You may specify -M multiple times. stack 'em up like friendship bracelets 🫶
• -m, --multiarch — builds a multi-architecture PAR file. Implies -p, so it's lowkey doing two things at once. queen behavior 👑
• -n, --noscan — skips the default static scanning altogether, using run-time dependencies from -c or -x exclusively. no scanning, we're going off vibes only (well, off run-time deps at least 💀)
• -N, --namespace=NAMESPACE — adds all modules in the namespace into the package, plus all their dependencies. So if NAMESPACE is something like Foo::Bar then this will add every module Foo/Bar/Quux.pm, Foo/Bar/Fred/Barnie.pm etc. that can be located in your module search path. It mimics the behaviour of plugin loaders like Module::Loader. 📦✨

This is different from using -M Foo::Bar::, because that one insists on adding Foo/Bar.pm — which might not even exist in the above plugin scenario. sneaky little difference, but it matters fr fr.

You may specify -N multiple times. 💅

• -o, --output=FILE — the file name for the final packaged executable. your lil bundle's birth certificate 🎀
• -p, --par — create PAR archives only; do not package to a standalone binary. archive mode, no exec energy. 📁
• -P, --perlscript — create stand-alone perl script; do not package to a standalone binary. script girlie, not binary girlie. 📜
• -r, --run — run the resulting packaged script after packaging it. package it then immediately take it for a spin, obsessed 🏃‍♀️
• --reusable — EXPERIMENTAL ⚗️

Makes the packaged executable reusable for running arbitrary, external Perl scripts as if they were part of the package:

pp -o myapp --reusable someapp.pl
./myapp --par-options --reuse otherapp.pl

The second line will run otherapp.pl instead of someapp.pl. it's giving shapeshifter 🔮

• -S, --save — do not delete the generated PAR file after packaging. keeping the receipts 🧾
• -s, --sign — cryptographically sign the generated PAR or binary file using Module::Signature. your build, but with a wax seal 🔏✨
• -T, --tempcache — sets the program-unique part of the cache directory name that's used if the program is run without -C. If not set, a hash of the executable is used.

When the program is run, its contents are extracted to a temporary directory. On Unix systems, this is commonly /tmp/par-USER/cache-XXXXXXX. USER is replaced by the name of the user running the program, but "spelled" in hex. And XXXXXXX is either a hash of the executable or the value passed to the -T or --tempcache switch. so many X's, iykyk 🦋

• -u, --unicode — Note: This option is ignored for Perl 5.32 and above. 🚨

Packages Unicode support (essentially utf8_heavy.pl and everything below the directory unicore in your perl library).

This option exists because it is impossible to detect using static analysis whether your program needs Unicode support at runtime. (Note: If your program contains use utf8 this does not imply it needs Unicode support. It merely says that your program source is written in UTF-8.) 🧚

If your packed program exits with an error message like

Can't locate utf8_heavy.pl in @INC (@INC contains: ...)

try to pack it with -u (or use -x). that's the fix, bestie 💖

• -v, --verbose[=NUMBER] — increases verbosity of output lol, not me stating the obvious; NUMBER is an integer from 1 to 3, 3 being the most verbose. Defaults to 1 if specified without an argument. Alternatively, -vv sets verbose level to 2, and -vvv sets it to 3. spam those v's for maximum yapping 🗣️🔥
• -V, --version — display the version number and copyrights of this program. the flex section 👑
• -z, --compress=NUMBER — set zip compression level; NUMBER is an integer from 0 to 9, 0 = no compression, 9 = max compression. Defaults to 6 if -z is not used. squish it or don't, your call 💅

---

🌸 ENVIRONMENT 🌸

• PP_OPTS — command-line options (switches). Switches in this variable are taken as if they were on every pp command line. like a permanent mood board for your flags 🎀

---

📝 NOTES 📝

Here are some recipes showing how to utilize pp to bundle source.pl with all its dependencies, on target machines with different expected settings:

Stone-alone setup:

To make a stand-alone executable, suitable for running on a machine that doesn't have perl installed:

% pp -o packed.exe source.pl        # makes packed.exe
# Now, deploy 'packed.exe' to target machine...
% packed.exe                        # run it

Perl interpreter only, without core modules:

To make a packed .pl file including core modules, suitable for running on a machine that has a perl interpreter, but where you want to be sure of the versions of the core modules that your program uses:

% pp -B -P -o packed.pl source.pl   # makes packed.pl
# Now, deploy 'packed.pl' to target machine...
% perl packed.pl                    # run it

Perl with core modules installed:

To make a packed .pl file without core modules, relying on the target machine's perl interpreter and its core libraries. This produces a significantly smaller file than the previous version:

% pp -P -o packed.pl source.pl      # makes packed.pl
# Now, deploy 'packed.pl' to target machine...
% perl packed.pl                    # run it

Perl with PAR.pm and its dependencies installed:

Make a separate archive and executable that uses the archive. This relies upon the perl interpreter and libraries on the target machine.

% pp -p source.pl                   # makes source.par
% echo "use PAR 'source.par';" > packed.pl;
% cat source.pl >> packed.pl;       # makes packed.pl
# Now, deploy 'source.par' and 'packed.pl' to target machine...
% perl packed.pl                    # run it, perl + core modules required

Note that even if your perl was built with a shared library, the Stand-alone executable above will not need a separate perl5x.dll or libperl.so to function correctly. But even in this case, the underlying system libraries such as libc must be compatible between the host and target machines. Use --dependent if you are willing to ship the shared library with the application, which can significantly reduce the executable size. 🫶

---

👀 SEE ALSO 👀

tkpp, par.pl, parl, perlcc

PAR::Packer::Troubleshooting, App::PP::Autolink, PAR, PAR::Packer, Module::ScanDeps

Getopt::Long, Getopt::ArgvFile

(the extended universe, go read it, no cap 📚)

---

💖 ACKNOWLEDGMENTS 💖

Simon Cozens, Tom Christiansen and Edward Peschko for writing perlcc; this program try to mimic its interface as close as possible, and copied liberally from their code. legends, truly 🫡

Jan Dubois for writing the exetype.pl utility, which has been partially adapted into the -g flag. king behavior 👑

Mattia Barbon for providing the myldr binary loader code. the realest ✨

Jeff Goff for suggesting the name pp. shortest, cutest name ever, we love a naming moment 🎀

---

🧚 AUTHORS 🧚

Audrey Tang cpan@audreyt.org, Steffen Mueller smueller@cpan.org, and Roderich Schupp roderich.schupp@gmail.com.

You can write to the mailing list at par@perl.org, or send an empty mail to par-subscribe@perl.org to participate in the discussion. Archives of the mailing list are available at https://www.mail-archive.com/par@perl.org/ or https://groups.google.com/g/perl.par. 🦋

Please submit bug reports to https://github.com/rschupp/PAR-Packer/issues. (do it, they're nice, i promise 🙈)

---

⭐ COPYRIGHT ⭐

Copyright 2002-2009 by Audrey Tang cpan@audreyt.org.

Neither this program nor the associated parl program impose any licensing restrictions on files generated by their execution, in accordance with the 8th article of the Artistic License:

"Aggregation of this Package with a commercial distribution is always permitted provided that the use of this Package is embedded; that is, when no overt attempt is made to make this Package's interfaces visible to the end user of the commercial distribution. Such use shall not be construed as a distribution of this Package."

Therefore, you are absolutely free to place any license on the resulting executable, as long as the packed 3rd-party libraries are also available under the Artistic License. go off, license it however you want 💅

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

See LICENSE.

---

and that's a wrap on this whole page, bestie!! 🎉 you just consumed pp(3pm), version perl v5.42.3, dated 2026-08-20 — yes the date is in the future, the manpage is simply ahead of its time, periodt. go pack something iconic ✨🎀