By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
424,493 Members | 1,231 Online
Bytes IT Community
Submit an Article
Got Smarts?
Share your bits of IT knowledge by writing an article on Bytes.

Simple guide to using PyInstaller

P: 92
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

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\pyinstaller13, 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 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 . (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:

Expand|Select|Wrap|Line Numbers
  1. #!/usr/bin/env python 
  2. for i in xrange(10000): 
  3.     print "Hello, World!"
Create this with your favorite editor and save it as 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:

Expand|Select|Wrap|Line Numbers
  1. set PIP=c:\python25\pyInstaller13\
  2. python --onefile --console --upx --tk
  3. python 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 file. See the notes at the end for the basics regarding those command-line options.

You should now have two files, 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:
Expand|Select|Wrap|Line Numbers
  4.     --tk        This is required for inclusion of the tcl/Tk
  5.             libraries.  Unlike py2exe, PyInstaller doesn't 
  6.             recognized that this is used and include it
  7.             automatically.  However, you can leave it in
  8.             without doing any harm (as we did in this
  9.             example).  It adds some overhead, but the size
  10.             seems to vary.
  12.     --upx        I mentioned that this is a great option, and 
  13.             it is, but it's really slow, especially as your
  14.             source file gets bigger.  It's a great option
  15.             for your final compile before distributing, but
  16.             you might save a lot of time if you turn it off
  17.             until then.
  19.     --console    This is the DOS-like box, and carries the same
  20.     --noconsole    significance as the python vs. pythonw usage 
  21.             for your other programs.  If your program runs
  22.             in Windows and you've finished troubleshooting,
  23.             you probably want --noconsole.
More info is available at, including some not-too-lengthy documentation pages.


- Mark
Dec 21 '06 #1
Share this Article
Share on Google+

Expert 5K+
P: 6,596
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.
Dec 21 '06 #2

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

thanks ..
Jan 23 '08 #3

P: 1
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.
Jul 21 '08 #4

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

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\lib\encodings\__init__.pyc)
W: delayed eval hack detected at line 0 - os (C:\Python25\lib\os.pyc)
W: delayed conditional exec statement detected at line 0 - iu (c:\python25\pyInstaller1.3\iu.pyc)
W: delayed conditional exec statement detected at line 0 - iu (c:\python25\pyInstaller1.3\iu.pyc)
Jul 22 '08 #5

P: 3
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\Scripts>python c:\python25\pyInstaller13\ 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?
Nov 16 '08 #6

P: 1
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,
Feb 12 '09 #7

P: 3
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/ 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 before building!"
SyntaxError: invalid syntax

Any suggestions?
Jun 17 '09 #8

P: 3
PS: I am using Windows Vista.
Jun 17 '09 #9

P: 2

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 files

Could you help ?
Apr 20 '11 #10

P: 1
I did everything you said, when i clicked on the .bat file, NOTHING happened. Am I missing something?
Thanks for your answer and best regards.
Dec 27 '15 #11