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:
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:
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:
More info is available at www.pyinstaller .org, including some not-too-lengthy documentation pages.
Cheers,
- Mark
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:
Code:
#!/usr/bin/env python for i in xrange(10000): print "Hello, World!"
Code:
set PIP=c:\python25\pyInstaller13\ python %PIP%Makespec.py --onefile --console --upx --tk HelloWorld.py python %PIP%Build.py HelloWorld.spec
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:
Code:
--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.
Cheers,
- Mark
Comment