Simple guide to using PyInstaller

[true911m]

This is a simple walkthrough to get PyInstaller up and running.

I decided to give PI a try, because it claims to be more selective about what it bundles into its executable files by default, and it also integrates UPX (Ultimate Packer for eXecutables) into the build process, if you have it installed. It also claims functionality on linux, as a bonus (I didn't test this). I highly recommend the UPX options, and will cover how to get it working on Windows.

At the time of this writing, the latest stable version of PyInstaller is 1.3, and UPX is 2.03.

The result here will be to convert a simple python app into a single .exe file that can be copied and run on any Windows XP machine. It may work on many other Windows platforms (and linux), but I haven't tested it.

You'll need a working Python installation before you continue. PyInstaller claims compatibility with versions 1.5 through 2.4. I'm running 2.5, and it's working just fine.

You can download PyInstaller from SourceForge at http://www.pyinstaller.org/.

PyInstaller does not install under Python's site-packages directory as most libraries do. Instead, you can put the contents of its directory (what you see when you unzip the download file) wherever you wish, but remember that you will either have to type its location or alter your system paths for the build process to work properly, so try to keep it relatively short. I haven't even tried the paths option, so if you try it and it works, drop a note here. My install location is c:\python25\pyi nstaller13, which means I took all those files from the archive folder and simply copied them to the install folder. Make a note of this path, because you'll have to substitute yours if it's different.

PyInstaller needs to be configured. Since it's compatible with all those Python versions, it needs to know which one it's working with. It's simple, though -- open the directory where you just copied those files, and double-click on Configure.py. PI will scan your Python install dirs, and make a config.dat file that customizes it for your installation.

Next, go ahead and download UPX from http://upx.sourceforge.net/#download . (I'm using the Win32 Console package). For the purposes of PyInstaller, you only need one file, upx.exe, placed in your system path. After unpacking the archive, copy upx.exe to your c:\pythonXX directory. That's all there is to it.

I'm starting with a basic Hello World app that I used in my prior walkthrough:

#!/usr/bin/env python 
for i in xrange(10000): 
    print "Hello, World!"

Create this with your favorite editor and save it as HelloWorld.py. Next, create a batch file to run the build process. Remember that path where you copied PyInstall? You'll need that here, on the first line below. Back to your editor to type the following:

set PIP=c:\python25\pyInstaller13\
python %PIP%Makespec.py --onefile --console --upx --tk HelloWorld.py
python %PIP%Build.py HelloWorld.spec

You can use whatever naming convention you wish, but because this may vary for each project, I'm saving it as HelloWorld.bat, right next to my HelloWorld.py file. See the notes at the end for the basics regarding those command-line options.

You should now have two files, HelloWorld.py and HelloWorld.bat, both in the same directory.

Double-click on HelloWorld.bat and sit back. Depending on your hardware, it could take from a couple seconds to a minute to complete. It seems to take a bit longer than the comparable py2exe build I described recently, and the UPX compression usually seems to add the most time, but this example should be pretty quick.

When the cmd window finishes, check the directory where you stored the two files. You should now see a new directory (buildHelloWorld) and a few new files (HelloWorld.spec, warnHelloWorld. txt, and HelloWorld.exe). The build directory and the .spec file were used by PyInstaller, and can be deleted. the warnXXX.txt file contains warnings; it seems these are always here, but so far they don't affect the program at all. And the .exe file is ready to go.

If you saw my py2exe walkthrough, you may remember that HelloWorld.exe topped out at 3.2MB from my 110-byte source file. This one weighs in at 1.5MB, a considerable improvement. In larger projects, where external .dlls and other resources are bundled into your project, the differences should be even more significant.

Go ahead, double-click on HelloWorld.exe, I know you want to...

Copy HelloWorld.exe to another computer (without Python on it), and run it there, just to see that it really works.

A few notes:

Just like py2exe, PyInstaller bundled a python interpreter, any required DLLs, and any referenced libraries in its output file, turning 100 bytes into 1.5MB. However, this is much smaller than the 3.2MB results from py2exe.

When you create HelloWorld.bat, above, you want to make a couple of simple choices based on each program you're 'compiling'. Here's the quick summary:

 
 
 
    --tk        This is required for inclusion of the tcl/Tk
            libraries.  Unlike py2exe, PyInstaller doesn't 
            recognized that this is used and include it
            automatically.  However, you can leave it in
            without doing any harm (as we did in this
            example).  It adds some overhead, but the size
            seems to vary.
 
    --upx        I mentioned that this is a great option, and 
            it is, but it's really slow, especially as your
            source file gets bigger.  It's a great option
            for your final compile before distributing, but
            you might save a lot of time if you turn it off
            until then.
 
    --console    This is the DOS-like box, and carries the same
    --noconsole    significance as the python vs. pythonw usage 
            for your other programs.  If your program runs
            in Windows and you've finished troubleshooting,
            you probably want --noconsole.
 

More info is available at www.pyinstaller .org, including some not-too-lengthy documentation pages.

Cheers,

- Mark

[bartonc]

I like your style, Mark. This is great info and I can see that you have gone to some trouble to get it to our members. I also see that you are now linking threads. This is awesome member partisipation! Thank you so much.
I made this one sticky, so here is a link back to the py2exe thread.

[naamakat]

How can I pack a more complicated structure of files ? any project have several directories - how can I manage a Tree of files ?

thanks ..

[dayneKnight]

Excellent guide Mark! Really easy to follow and it actually worked. You saved me a lot of time in a project I'm working on. Thanks very much!

Since you obviously have a skill with explaining complex topics clearly, I hope you'll consider posting a few more guides.

[shadowlink]

Hey, I've been trying to get pyInstaller to work but i'm getting the following problems.
Can someone help me out with this?

(warnHelloWorld .txt)

W: no module named posix (conditional import by os)
W: no module named pwd (delayed, conditional import by posixpath)
W: no module named win32api (delayed import by iu)
W: no module named posix (delayed, conditional import by iu)
W: no module named org (top-level import by copy)
W: no module named _emx_link (conditional import by os)
W: delayed __import__ hack detected at line 0 - encodings (C:\Python25\li b\encodings\__i nit__.pyc)
W: delayed eval hack detected at line 0 - os (C:\Python25\li b\os.pyc)
W: delayed conditional exec statement detected at line 0 - iu (c:\python25\py Installer1.3\iu .pyc)
W: delayed conditional exec statement detected at line 0 - iu (c:\python25\py Installer1.3\iu .pyc)

[dbpeckham]

The instructions are great but they did not work for me. Here is what I see when I run the HelloWorld.bat file:

c:\Python25\Scr ipts>python c:\python25\pyI nstaller13\Buil d.py HelloWorld.spec 'python' is not recognized as an internal or external command, operable program or batch file

I get the "'python' is not recognized..." note when I enter the word 'python' before any .py script.

Any ideas?
Don

[GeertVc]

@dbpeckham
1 reason, 2 solutions:

1. the directory where python.exe resides, is not part of your PATH variable

1. add the directory where python.exe resides, to your PATH environment variable
2. prefix "python" in the batch file with the complete path

That should solve your issue.

Best rgds,
--Geert

[dbpeckham]

I gave up on pyInstaller several months ago but I'm trying again.

I copied the upx.exe file to c:/python25/

I ran c:/python25/pyInstaller-1.3/Configure.py and got the following response:

I: Finding TCL/TK...
I: found TCL/TK version 8.4
I: testing for Zlib...
I: ... Zlib available
I: Testing for ability to set icons, version resources...
I: ... resource update available
I: Testing for Unicode support...
I: ... Unicode available
I: testing for UPX...
I: ...UPX unavailable
I: computing PYZ dependencies...

I ran HelloWorld.bat and got the following response:

..."You must run Configure.py before building!"
SyntaxError: invalid syntax

Any suggestions?

[dbpeckham]

PS: I am using Windows Vista.
dbpeckham

[Stef le Breton]

Hi,


I'm also very interested having more information on how to compile a more structures projects with different directories with lib imported in the higher script and empty __init__.py files

Could you help ?