Mar 15th 2025
About Perl2exe
System Requirements
Installation
Perl2Exe is a command line utility for converting Perl scripts to executable files.
This allows you to create stand alone programs in perl that do not require the perl interpreter. You can also ship the executable file without having to ship your perl source code.
Perl2Exe also allows you to create no-console programs using Gtk or Tk.
Perl2Exe for Unix can generate executables for supported Unix machines. Perl2Exe for Unix can also be used from a Windows host to generate executables for a Unix target host.
This document covers Perl2Exe V6.00 and later.
perl2exe [options] myscript.pl
This will convert a script named myscript.pl to myscript.exe.
| -v | Verbose output Verbose supports optional sub options. -v print list of modules used -v=from Print location where the module was referenced |
| -register | This option allow you to enter registration information for Perl2Exe. You will be prompted for a registration key. |
| -small | Generates a smaller executable which uses a shared runtime DLL.
The generated executable will be smaller by about 600KB. The
executable will require a shared DLL, p2xXXX.dll to run. This DLL
will be copied to the current directory.
Applies to the Pro version on Windows only. |
| -tiny | Create an even smaller executable by placing additional code into DLL's. Perl2Exe will create DLL files in the current directory containing code from loadable modules which use pll, dll, or so files. This option is not available in the Lite versions of Perl2Exe. |
| -gui |
Create a no-console executable. This can be used for Tk and Win32::GUI applications. I/O to STDOUT and STDIN will not be visible. If your application does not work do not use the -gui option while testing as it will hide possible error messages. Applies to Windows version only. |
| -icon=filename |
Add a user supplied icon to the executable. The icon must contain a Standard(32x32) and a Small(16x16) bitmap and must be 1078 bytes long. How to create the required icon using Dev Studio: Icons will not display on Win95 systems unless IE is also installed. Applies to Windows version only |
| -o=filename | Specify the output filename. |
| -platform=SunOS -platform=Linux etc |
Specify the target platform for the executable. The default
is based on the host machine. On a Linux host the default is
linux, on a SunOS (Solaris) host the default is SunOS. For a
full list of available platforms type the command 'perl2exe'.
|
| -noopt | Disable some optimization. |
| -I=dir1:dir2 | This will cause Perl2Exe to search in additional directories for modules |
The following comments in your source code will affect the way that perl2exe operates.
| #perl2exe_include modulename | Add the named module to the executable. Examples: #perl2exe_include Data::Dumper #perl2exe_include "Data/Dumper.pm" |
| #perl2exe_exclude modulename | Exclude the named module from the executable. Examples: #perl2exe_exclude Data::Dumper #perl2exe_exclude "Data/Dumper.pm" |
|
#perl2exe_noopt |
Disable optimization for the current source file |
| #perl2exe_noopt modulename | Disable optimization for the named modules |
| #perl2exe_bundle filename | The named file will be added to the executable. At run time
the file will be extracted to a temp directory where it can used by
your application for any purposes. The file will be removed
when the program exits. The temp directory is given by:
$temp_dir = ( $ENV{TEMP} || $ENV{TMP} || $ENV{WINDIR} || '/tmp' ) . "/p2xtmp-$$"; Example: |
| #perl2exe_info name=value | This pragma is used to set file version information for Windows
executables.
Values are strings except FileVersion which must be of the form 'W.X.Y.Z' (where W, X, Y, and Z are numbers in the range 0-65535. X, Y, and Z are optional and default to 0). Name is one of the following list. CompanyName, FileDescription , FileVersion, InternalName, LegalCopyright, LegalTrademarks, OriginalFilename, ProductName, ProductVersion, Comment. |
1. Contacting us for support
If you are having trouble getting your executable to run, please
send us the following information:
2. Building your executable
Build your script with the command:
perl2exe yourscript.pl
Perl2Exe will automatically scan your source code for use and require statements. Required source modules (".pm" files) and autoloadable (.dll and .so files) will be automatically compiled into the executable file. On Windows perl.exe must be in your path.
Perl2Exe may print warnings about missing modules. If the module really does not exist the warning can be ignored. You can suppress the warning message by adding a '#perl2exe_exclude' pragma line to your script.
Perl2Exe can handle most scripts without any changes. If your script contains any 'use lib' statements, comment out the statements and use a -I command line option to cause Perl2Exe to look in additional non-standard directories..
3. Testing your executable
Test the executable by running it from a command line prompt.
If it dies with a "Can't locate somemodule.pm in @INC ... " error message, then add an explicit use statement for the missing module to your script.
Do not use the -gui option while testing as it will hide possible error messages.
If the executable still fails to run properly try running it with a -p2x_test option. If this produces error messages about a missing then add an explicit #perl2exe statement for the missing file to your script. If the file really does not exist on your system then the message can be ignored.
4. "Can't locate somemodule.pm in @INC at myscript.pl line 1"
error message
If you get an error message like the one above, you can force the
missing module to be compiled into the exe by adding a line like one of
the following to your script:
#perl2exe_include "somemodule.pm";
Or if the message is "Can't locate Foo/Bar.pm in ...":
#perl2exe_include "Foo/Bar.pm";
Please also send us the script with this problem, so we can fix the problem in a future version of Perl2Exe.
5. Perl2exe compatibility
Perl2Exe V26.10 for Windows is compatible with Perl 5.26.x
64-bit. ActivePerl and StrawberryPerl
Perl2Exe V24.10 for Windows is compatible with Perl 5.24.0 and Perl
5.24.1 64-bit. ActivePerl and StrawberryPerl
Perl2Exe V22.00 for Windows is compatible with Perl 5.22.0 32-bit and
64-bit. ActivePerl and StrawberryPerl
Perl2Exe V16.00 for Windows is compatible with Perl 5.16.3 32-bit and
64-bit, and Perl 5.14.4 32-bit and 64-bit.
Perl2Exe V11.00 for Windows is compatible with Perl 5.12.4 32-bit and
64-bit, and Perl 5.14.2 32-bit and 64-bit.
Perl2Exe V10.40 for Windows is compatible with Perl 5.12.4, Perl 5.12.3,
Perl 5.12.2, 5.12.1, Perl 5.10.1, Perl 5.8.9, Perl 5.6.1
Perl2Exe V10.30 for Windows is compatible with Perl 5.12.3, Perl 5.12.2,
5.12.1, Perl 5.10.1, Perl 5.8.9, Perl 5.6.1
Perl2Exe V10.10 for Windows is compatible with Perl 5.12.2, 5.12.1, Perl
5.10.1, Perl 5.8.9, Perl 5.6.1
Perl2Exe V9.100 for Windows is compatible with Perl 5.10.0, Perl 5.8.8,
Perl 5.6.1 Perl 5.005.
Perl2Exe V8.82 for Windows is compatible with Perl 5.8.8, Perl 5.8.7, Perl
5.6.1 Perl 5.005.
Perl2Exe V8.80 for Windows is compatible with Perl 5.8.8, Perl 5.8.7, Perl
5.6.1 Perl 5.005.
Perl2Exe V8.70 for Windows is compatible with Perl 5.8.7, Perl 5.8.6, Perl
5.6.1 Perl 5.005.
Perl2Exe V8.60 for Windows is compatible with Perl 5.8.6, Perl 5.8.4, Perl
5.6.1 Perl 5.005.
Perl2Exe V7.01 for Windows is compatible with Perl 5.8.0, Perl 5.6 Perl
5.005.
Perl2Exe V7.01 for Unix is compatible with Perl 5.8.0.
Perl2Exe V5.xx for Windows is compatible with Perl 5.6 and Perl 5.005.
Perl2Exe V5.xx for Unix is compatible with Perl 5.6.
Perl2Exe for Perl 5.6 is compatible with Perl 5.6.
Perl2Exe for Perl 5.005 is compatible with ActiveState's build 522 and
other 5xx builds.
Perl2Exe for Perl 5.004 is compatible with "Perl 5.004_02" from CPAN,
which is also called the standard build.
Perl2Exe for Perl 5.003 is compatible with "Perl, version 5.003_07, Perl
for Windows Build 316".
Perl2Exe V1.xx for Unix is compatible with Perl 5.00503.
6. Perl2Exe performance
Programs created with Perl2Exe will run at about the same speed
as Perl scripts run with the standard interpreter.
7. Using the glob function
Use the following code if your code uses the glob function:
use File::DosGlob 'glob';
@flist = glob "*.*";
8. Using dbmopen
If your script contains a dbmopen function call, add the
following two lines to your script.
use AnyDBM_File;
use SDBM_File;
For some systems you may need these lines instead:
use AnyDBM_File;
use NDBM_File;
use DB_File;
use SDBM_File;
9. Using the Tk library
If your script uses the Tk library it will be necessary to add
some additional use statements to your main script. Build your executable
in the normal way, then when you run the program, if you get a message
like "Can't locate Tk/Entry.pm in @INC", add "use Tk::Entry;" to your main
script.
If you see a message that says something like:
Can't find 'boot_IO' symbol in C:\WINDOWS\TEMP/IO.dll
Run the command:
ren c:\perl\site\lib\auto\tk\io\io.dll io.dll.save
10. Creating an NT services
Perl2Exe can be used to create NT services. Use the SRVANY
utility program which comes with Microsoft Resource Kit to start your
executable as a service. Configure SRVANY to start in the directory
where the executable is located. You will probably also need to use
the -tiny option.
11. Extra Modules bundled with Perl2Exe for Unix
DBD::mysqlPP , DBI, HTML::Parser, libwww-perl,
Net::MySQL, URI
12. How to tell if the program is compiled with perl2exe
# How to tell if the program is compiled with perl2exe
if ($^X =~ /(perl)|(perl\.exe)$/i) {
print "using perl interpreter\n";
}
else {
print "Program is compiled with perl2exe\n";
}
13. How to find the directory where the
your application is located.
# Next line is for Perl2Exe V5.02 and older
$0 = $^X unless ($^X =~ m%(^|[/\\])(perl)|(perl.exe)$%i);
my ($program_dir) = $0 =~ m%^(.*)[/\\]%;
$program_dir ||= ".";
print "program_dir = $program_dir\n";
14. Using DBD::mysql
Perl2Exe for Unix V7.00 or greater comes with the DBD::mysqlPP
module. We suggest that you use this mysqlPP module instead of the
mysql module. In your DBI open statement change DBI:mysql to
DBI:mysqlPP. Also add the following lines to your script:
use DBD::mysqlPP;
use Carp::Heavy;
15. How to use DBI with Perl2Exe
1) Add the following lines to your script:
use DBI;
use DBD::mysql;
Replace mysql with whatever driver you use in your DBI open statement.
Do not use the #perl2exe_include statements.
16. Using DBD::Oracle
If your application uses DBD::Oracle the Oracle client software must also be installed on the target computer. DBD::mysql does not have this limitation.
17. Running multiple instances of your program
When you run the executable it will extract any loadable modules that
it uses, like Socket.so, to a temp directory. These loadable modules are
loaded into memory later on. When the program exits the temporary files
are deleted.
This can fail if the temp directory is not write-able. On Windows the temp directory is given by $ENV{'TEMP'} || $ENV{'TMP'} || $ENV{'WINDIR'} || "."; and on Unix it is "/tmp".
To avoid this problem make sure the temp environment variable is set to point to a writeable directory or compile your script with the -tiny option. This will generate an executable and a number of dll or 'so' files. Copy the generated dll or so files to the same directory as the executable.
18. How to debug a CGI script
Instead of running the CGI executable from a web server, test the CGI executable by running it from a DOS window on Windows, or a telnet console on Unix. This will allow you to see any error messages that may be being printed.
If you don't have telnet or console access to your server add this code to the top of your script:
BEGIN {
$| = 1;
open (STDERR, ">&STDOUT");
print "Content-type: text/html\n\n<pre>\n";
}
If you get a message like: "Can't locate loadable object for module ..."
Compile your script with the -tiny option. This will generate an executable and a number of dll or 'so' files. Copy the generated dll or so files and executable to the same directory as the executable.
19. Building modules on Solaris with GCC
Some versions of Perl2Exe for SunOS will default to using the Solaris cc
C compiler for building modules. If you have GCC installed you will
need to make the following changes to the Config.pm file which will be
located somewhere like ~/perl2exe/perl5/lib/5.6.0/sun4-solaris:
cc='cc' -> cc='gcc'
ld='cc' -> ld='gcc'
cccdlflags='-KPIC' -> cccdlflags=''
20. How to create icons for Perl2exe
You can create your icons with IconForge from www.cursorarts.com or Microsoft DevStudio.
For IconForge install the software and follow the directions below.
1) Go to the "File" menu and choose "New";
2) Choose "New Multi-resolution Icon" from the fly-out list;
3) This will open a small window which will hold the various icon sizes
which you want to place inside the main icon. Click the green "+" button,
and choose a size of "16x16" with "16 colors";
4) A small blank icon will be added to the window. Double-click this to
paint this icon;
5) Once you have finished your icon, File/Save it back into the
Multi-resolution Icon window;
6) Click the green "+" button to add another icon, and choose a size of
"32x32" with "16 colors";
7) This will add a larger icon to the window. Click your completed smaller
icon to highlight it, then click the "Duplicate" button (has a blue circle
icon) to copy your smaller icon into the blank larger frame. You can then
further edit the larger icon if you wish;
8) Once you have finished editing, go to the "File" menu and select "Save
As" from the list. Assign a name for the new icon, using the .ICO File
Type.
Save the icon in the same directory as your script.
For DevStudio follow the directions below.
1. Click on File, New
2. Click on Files then 'Icon File'
3. Draw the 32x32 portion of your icon
3. Click Image then 'New Device Image'
4. Click on 'Small (16x16)' then OK
5. Draw the 16x16 [portion of your icon
6. Click on File, 'SaveAs' to save your icon file
Save the icon in the same directory as your script.
After saving the icon, open a dos window, and type in the following:
perl2exe -icon=youricon.ico yourscript.pl
21. Stripping comment lines
Perl2Exe will remove all lines from scripts that start with the
'#' character. If this a problem, you can override this behavior by
using the -noopt option. The -noopt option will disable the
stripping for all source files. Do disable it for selective files
only use the #perl2exe_noopt pragma. Example:
#perl2exe_noopt Foo
or
#perl2exe_noopt "Foo.pm"
or
#perl2exe_noopt "bar.pl"
Most versions of Windows, Linux, MacOSX, and Unix
Unzip the installation file to c:\
This will create a subdirectory like perl2exe-26.00-Win
If you have a registration key for Perl2Exe, start perl2exe with the
command:
perl2exe -register
This option allow you to enter registration information for Perl2Exe. You will be prompted for a registration key.
Extract Perl2Exe for Linux, Solaris, AIX, etc into the installation directrory.
For Windows, extract Perl2Exe for Windows. This will create
a directory like the following:
~/perl2exe-Linux-5.14.2/perl2exe-11.00-Win
Copy the perl directory from c:\perl on your Windows machine to one of
the following directories depending on your version of Perl:
~/perl2exe-Linux-5.14.2/perl2exe-11.00-Win/Win32-5.12.4/perl-Win32/perl-Win32
~/perl2exe-Linux-5.14.2/perl2exe-11.00-Win/Win32-5.14.2/perl-Win32
~/perl2exe-Linux-5.14.2/perl2exe-11.00-Win/Win64-5.12.4/perl-Win64
~/perl2exe-Linux-5.14.2/perl2exe-11.00-Win/Win64-5.14.2/perl-Win64