Last Updated: Wednesday 14th August 2013

PyInstaller is a program used to convert Python scripts into standalone applications. PyInstaller allows you to run applications written in Python on a computer without requiring the user to install Python. It is an excellent option when you need to distribute a program to the end user as a standalone application. PyInstaller currently only works with Python 2.3 up to 2.7.

PyInstaller claims to be compatible with a lot of third party libraries or packages out of the box. PyQt, Django and matplotlib are fully supported.

To start, download and extract PyInstaller from the official site.

PyInstaller is an application, not a package. So there is no need to install it in your computer. To get started, open a Command Prompt (Windows) or a Terminal (Mac and Linux) and go to the PyInstaller Folder.

Now suppose you want to package, I saved it into the pyinstaller folder:

Then, in order to create the executable just run python and you will see a lot of output and a folder called myscript will be created, with two folders and a file inside. The build folder is used by PyInstaller as a temporary folder to create the files needed for the executable. The dist folder stores the executable and all of the files needed in order to run that executable. It is safe to delete the build folder. The file called myscript.spec is useful to customize the way PyInstaller packs your application.

Now test if your executable works:

You should see now a "Hello World!" printed on the screen.

Remember that running python assumes that you have Python in your path environment variable. If that is not the case, just use C:\Python27\python.exe in Windows. Most of the time on Linux and Mac OS X, Python will be in your path environment variable.

GUI Applications

Now it is time to create a GUI application. In this example we will be using Tkinter:

To pack it, it is mandatory to use the --windowed flag, otherwise the application will not start:

In this moment you can navigate to the dist folder and run the application by double clicking it.

Note for Mac OS X users: the above example using Tkinter works fine if you use the pre-installed Python version, if you installed or updated Python by yourself, you can find some problems running the packaged application.

Using External Modules

The previous examples were importing modules from the Python Standard Library. PyInstaller includes the Standard Library Modules by default. However if we installed a third party library, PyInstaller is likely not to include it. In most of the cases we need to create "hooks" to tell PyInstaller to include these modules. An example of this is an application using the ReportLab library to make PDF files:

A "hook" module is a Python file with a special name, used to tell PyInstaller to include a specific module. Doing a Google search i found the needed hooks to pack a ReportLab application here and placed them in a folder named "hooks":

+- hooks/
|- and are empty files, contains:

Now in order to pack the executable, we have to run python --additional-hooks-dir=hooks/ The additional-hooks-dir flag tells PyInstaller to search for hooks in the specified directory.


Pyinstaller works great if your script only imports modules from The Python Standard Library, or a module included in the official Supported Packages list. Using these supported packages make packaging applications pretty straightforward, but when wee need to use a third-party not supported module, it can be tricky to make it work.

To Practice: Try this interactive course on the basics of Lists, Functions, Packages and NumPy in Python.

  • Mary Kindall

    I am trying to create python executable using PyInstaller package following your post.

    The PyInstaller compiles my super simplified example code below without any error but gives error during runtime. This is because I am using “xlrd” package which is considered a `non-standard` package. The “xlrd” package was downloaded from

    I was lost at the point where I needed to create the ‘hooks’

    Which file do I need to include (and where) and what will be its content?


    print(“inside the file: Working here…”)
    import xlrd

    HP-ZBook-15:~/Desktop/hello/dist/hello$ ./hello
    inside the file: Working here…
    Traceback (most recent call last):
    File “”, line 2, in
    ImportError: No module named xlrd

    I am sure it will be easy for you to suggest me a fix.

    • Hey Mary,

      I haven’t used xlrd before, but PyInstaller looks for import statements and attempts to include the libraries. So many of them will work without needing hooks. Although some fail, and that’s why hooks are required.

      I just tried your example with xlrd, and it worked fine. I’m on a Mac, using the latest (from the repository) PyInstaller version. What command did you use to generate the binary? I simply used --onefile

      Also make sure that you execute PyInstaller with the same Python binary that you use to run the script normally. Sometimes you’ll have multiple installs of Python, and only one has the library available. eg. /usr/local/bin/python vs /usr/bin/python. Failing that, you can also use the --hidden-import argument when executing PyInstaller, which explicitly tells it to include the xlrd library.

      Hope that helps 🙂

  • Ankit

    i want to know , in which tool we can design Form Like Vb.Net,Asp.Net,Html.
    Python has no Tools For Designing..
    tell me name of tools.

  • Michael Gaidamaka

    hi, Andres Torres. Can you help me to pack mayavi or another package from enthought by pyinstaller?

  • carlos cuesta

    andres esto se ve muy vacano pero como se instala esto sobre windows por que nadie dice los pasos precisos todo es muy ambiguo como por si lo averigua y de chepa le da

  • Alejandro Ventura

    What about using Python 3.4.3? Now it supports this Python version.

  • Joe

    Best Tutorial! Searched the whole evening for correct using of PyInstaller. THX

  • Rishikesh Agrawani

    Great & Nice article…

  • Seghier Mohamed Abdelaziz

    than how the exe find the external module ?
    i tried without success ; the hook just remove the module