How to Report Bugs

If you submit enough information about your problem, we will be able to help you quicker.

Before submitting a report: Make sure it's a bug

• Start with a clean Installation of the most recent release.
• Remove the config and cache files by simple deleting the directory
  • on Linux: $XDG_DATA_HOME/pyinstaller or ~/.local/share/pyinstaller
  • on Windows: %APPDATA%\pyinstaller (or ~\Application Data\pyinstaller)
  • on Mac OS X: ~/Library/Application Support/pyinstaller
• for PyInstaller prior to version 1.5 delete config.dat and bincache* in PyInstallers installation directory

Before submitting a report: Make sure everything is packaged

If a program get packaged fine, but the resulting application crashes, this most often is caused by missing files in the package. If you get ImportErrors of File not found messages, you can be very sure, this is the case.

• Note: Try solving the problem in --onedir mode. This is much easier since you can easily see what gets collected.
• Note: The tool utils/ArchiveViewer.py can be used to look into the packed application (the .exe file) and verify all required modules and data-files are there. You'll have to look into outPYZ*.pyz, too. Please see the the manual for how to use ArchiveViewer.

• If you do not have any idea about what is missing, try looking at the files and dlls you program is using.
  • On Unix/Linux use strace -e trace=open (or ... trace=file) to see which files are fail reading. Mind redirecting stderr into a file (2>/tmp/trace.log).
  • On Windows use one of these tools:
    • Sysinternals  Process Explorer,  ListDLLs or  Process Monitor
    •  Dependency Walker
    •  StraceNT

• If some data file (e.g. an icon or a language text) is missing, try to collect all data files, see Recipe/CollectDatafiles.
• If some module is missing (e.g. ImportError):
  • The module needs to be either in the archive outPYZ*.pyz or the current directory. Since the import fails, it most probably will be missing at both places.
    • All pure Python modules should be collected into outPYZ*.pyz. The names used in this archive are the full qualified module names (e.g. sphinx and sphinx.pycode.nodes). Use ArchiveViewer.py to check whether the module is in the archive.
    • Shared libs (.so, .dll, .pyd, etc.) are not put into the executable but only collected into the dist directory. Again, the names are full qualified module names, but with extension (e.g. mx.DateTime.mxDateTime.mxDateTime.pyd).
  • In build/logdict*.log you'll find the dependencies. If the module is missing here, some dependency did not get resolved. Please search for "decorators", nor for the qualified module name. This may expose the error.
  • In build/pyi.*/YourProject/warn*.txt you'll find the warnings, esp. missing modules. If the module is listed here, try to solve the warning.
  • Is it a hidden import? Then try a writing hook. Please see the manual for more information about hidden imports and hooks. Please submit the hook it may be of interest for others, too.
• Try without UPX packaging, say: use the option --noupx. Some libraries are known to not work with this.
• Repackage you application in verbose/debug mode. For this, pass the option --debug to MakeSpec.py resp. pyinstaller.py or use EXE(..., debug=1, ...) in your .spec file.

If the problem still pertains, it looks like a bug :-\

When submitting a bug: Information we need

• What is the exact problem?
  • Does the error occur when bundling the application or when running it?
  • If you have an import error, please submit the last part of the traceback. This helps a lot to see which modules tried to import which other one.

• Software versions you are using.
  • version of Python
  • exact version of PyInstaller (when using svn trunk, please state the revision number)
  • exact version of the 3rd-party module trapping the error

It's best to paste the download-URL. If you are using a develeoper snapshot, please state the exact revision and/or date.

• What platform and which version you are working on (Windows, Linux, OS X).

For Linux please specify the distribution and version - for the case it works out to be relevant.

• If you have several platform available, please try on another one. Does the problem occur there, too?

• A minimal example program which shows the error. Ideally this is a one-liner :-)

• Did you try implementing a hook or run-time-hook (rthook) to solve the problem? If so, please include the hook file.

• Please include any other information which you think may by helpful for fixing, while reducing as much a possible. Please add logfiles as attachments.

• Please try latest development version and let us know if the bug is already fixed there.

Thanks a lot!