1. Can I use PyInstaller as a cross-compiler?
    1. Can I package Windows binaries while running under Linux?
      No, this is not supported. Please use Wine for this, PyInstaller runs fine in Wine. You may also want to have a look at this thread in the mailinglist. In version 1.4 we had build in some support for this, but it showed to work only half. It would require some Windows system on another partition and would only work for pure Python programs. As soon as you want a decent GUI (gtk, qt, wx), you would need to install Windows libraries anyhow. So it's much easier to just use Wine.
    2. Can I package OS X binaries while running under Linux?
      This is currently not possible at all. Sorry! If you want to help out, you are very welcome.
  2. Does PyInstaller build a real installer like NSIS or InstallShield?
    No, despite its name (which has more to do with its historical roots), PyInstaller is used to transform a Python program into a native executable form which does not require existing Python installations to run. Building an installer program is totally outside the scope of PyInstaller.

If Things Go Wrong

There are different areas of typical problems which can occur when using PyInstaller. For fixing problems in your application, it is critical to understand this.

  1. Some required modules, shared libs or data files are not frozen (packaged, bundled) into the resulting exec. This kind of problems are to be solved within the "freeze" phase by
  • using hiddenimport in the .spec-file. (this is new feature in current development branch)
  • collecting files or modules within the .spec-file
  • implementing a new hook (or fixing an existing one)
  • fixing a bug in PyInstaller.

To check if all your files are frozen, use utils/ See Make sure everything is packaged for more information.

  1. You application can not import some module, list modules, find data files, etc. This kind of problems has to be solved within our application by:
  • adapting your application to be frozen (see the manual)
  • If generic parts of your application are effected (e.g. commonly used packages like Tkinter, GTK, QT), adding a runtime-hook will help others users

Prior to solving "Type 2" problems, yo need to ensure there are no "Type 1" problems. You first of all you need to find out which type of problem you are facing. See HowtoReportBugs for how to do this.

Please note: If your application is complex, there may be several "Type 1" and several "Type 2" problems.

  1. PyInstaller crashes when packaging my program
    Please try the development version (zip, tar.gz) first. If even this version does not work, it looks like a bug. Please have a look at HowtoReportBugs, which will help us a lot on solving the problem.
  1. I get an ImportError when running the packaged version. What should I do?
    Please make sure, all modules required by you application are packaged. See Make sure everything is packaged for more information.
  1. My program crashes when running the packaged version. What should I do?
    Please make sure, all data files required by you application are packaged. See Make sure everything is packaged for more information.
  1. I made it work by implementing a hook. Do you want it?
    Yes, we'll happily integrate any hook which may be of interest for others. Please open a ticket and attach the hook.


  1. Can I use PyInstaller for my commercial, closed-source, Python application?
  2. If I use PyInstaller for my commercial Python application, will I have to distribute my source code as well?
    Absolutely not. You can ship the executables created with PyInstaller with whatever license you want.
  3. If I use PyInstaller for my commercial Python application, will I have to advertise/mention/display that PyInstaller is being used, for instance by quoting its copyright line?
    Absolutely not. But we will love you if you do.
  4. I need to modify PyInstaller for my own needs. Can I do that?
    Of course, PyInstaller is free software. This falls under the terms of the GPL license: you can modify PyInstaller as you wish, but if you distribute your modifications (so-called derived work), you will have to do that under the GPL license. In short, you can't change the license of PyInstaller.
  5. Can I modify PyInstaller, use it for a commercial product, and never release nor distribute my modified version of PyInstaller?
    Depends. PyInstaller source code is logically divided into two parts: one part is the builder itself, which constructs the executable. The other is the bootloader, which is embedded within the final executable. If you modify only the builder, then the answer is yes. If you modify also the bootloader, the answer is no: in fact, by distributing the final product you are also distributing a binary version of the bootloader, so you are forced to release the source code for your modified version.
    • How can I tell the bootloader from the builder?
      Just read the license at the top of each file. If it contains a paragraph with a special exception, then the file is part of the bootloader. Otherwise, it is part of the builder.
    • This is too hard for me. I want a simpler rule.
      Always contribute your modifications back to us. This is easier to remember, and it is also a nice way to show that you appreciated our program. We will do our best to integrate your patches into PyInstaller!


  1. With PyInstaller, I don't get Windows XP themes in my application with wxPython!
    Make sure you are using at least PyInstaller 1.3, and that you are building a windowed mode executable (pass -w to
  2. What about .egg files?
    PyInstaller trunk fully supports .egg files: they are bundled as-is. In one-dir mode, you will see them on the filesystem; in one-file mode, they will be unpacked within the temporary directory along with dynamic libraries. This is actually a workaround, but it is better than nothing, and makes sure that all .egg features (eg: entry points, pkg_resources, etc.) work correctly. Notice that PyInstaller does inspect .egg files at build-time and correctly looks for dependencies they have.
  3. What about pkg_resources?
    pkg_resources is currently not supported by PyInstaller. This means that an application using a library which uses the the pkg_resources API will probably not work out of the box. The only situation in which it works is when it's being used on .egg files (see above).
  4. Under Linux, I get runtime dynamic linker errors, related to libc. What should I do?
    The executable that PyInstaller builds is not fully static, in that it still depends on the system libc. Under Linux, the ABI of GLIBC is backward compatible, but not forward compatible. So if you link against a newer GLIBC, you can't run the resulting executable on an older system. The supplied binary bootloader should work with older GLIBC. However, the and other dynamic libraries still depends on the newer GLIBC. The solution is to compile the Python interpreter with its modules (and also probably bootloader) on the oldest system you have around, so that it gets linked with the oldest version of GLIBC.
  5. Can I use PyInstaller with other Python distributions?
    The primary development and testing of PyInstaller is focused on official Python releases available from Python website. Other Python distributions like ActiveState or Enthought may or may not work. ActiveState might work on Windows (see #351).
  6. How to get recent Python environment working on old Linux distribution?
    The issue is that Python and its modules has to be compiled against older GLIBC. Another issue is that you probably want to use latest Python features and on old Linux distributions there is only available really old Python version (e.g. on Centos 5 is available Python 2.4). The following tools could help you to set up environment with recent Python on old Linux distribution:
  7. How to set up manageable Python environment on Mac OS X?
    Mac OS X does not have any package management system like it is in many Linux distributions. To manually compile all libraries you need for application is a pain. To ease this process you could try any of the following package management system for Mac OS X:
  8. Created binary does not work on Mac OS X and I get message like
    This program needs access to the screen. Please run with 'pythonw', not 'python', and only when you are logged in on the main display of your Mac.
    This happens when you develop a GUI application for Mac. For GUI applications you need to use the precompiled bootloader linked with graphical Mac OS Xlibraries. You could do that with option --windowed.
  9. How to create application bundle (.app) on Mac OS X?
    The .app bundle is created automatically with the --windowed option.


Last modified 23 months ago Last modified on Nov 7, 2012 4:21:58 PM