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.
   These kinds of problems can be solved within the "freeze" phase by:

   • using hiddenimport in the .spec-file.
   • collecting files or modules within the .spec-file
   • implementing a new hook (or fixing an existing one)
   • ensure you have all required shared libraries on the local system. This is especially important if the local system is something like a Docker image running in a CI setup. Note that pip does not install all such dependencies, for example for PyQt.
   • fixing a bug in PyInstaller.
     
     

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

2. 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 affected (e.g. commonly used packages like Tkinter, GTK, QT), adding a runtime-hook will help others users

Prior to solving "Type 2" problems, you 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 Before submitting a report 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 How to Report Bugs, which will help us a lot on solving the problem.

2. 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.

3. I receive Failed to execute script. What should I do? Build the app without --windowed and run it from a command prompt to get the full error output before submitting a bug report.

4. 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.

5. 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. Or even better: submit a pull-request.

6. MacOS Big Sur GUI applications fail to render
   Try adding the following to the top of your main python file:

import os
os.environ["QT_MAC_WANTS_LAYER"] = "1"