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
• Please try latest development version. Simply use pip install https://github.com/pyinstaller/pyinstaller/archive/develop.zip to install the latest git version.

Make sure everything is packaged correctly

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 or File not found messages, you can be very sure, this is the case.

• Run your frozen program from a command window (shell) — instead of double-clicking on it — so you can see its output.

• Try packaging your program in --onedir mode. If this does work, but --onefile mode does not, this most times is an indicator for a problem within your application or one of the libraries you are using.

• Try without UPX packaging, say: use the option --noupx. Some libraries are known to not work with this.

• Important: Never use --onefile for debugging. Try solving the problem in --onedir mode. This is much easier since you can easily see what gets collected and digging into problems is much easier, too.

• Note: The tool pyi-archive_viewer 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 pyi-archive_viewer.

• Repackage you application in verbose/debug mode. For this, pass the option --debug to pyi-makespec or pyinstaller or use EXE(..., debug=1, ...) in your .spec file.

• If you do not have any idea about what is missing, try looking at the files and dlls your 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. you get an 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 pyi-archive_viewer 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.

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.
  • Is there anything striking in the debug-output? For this, pass the option --debug to pyi-makespec or pyinstaller or use EXE(..., debug=1, ...) in your .spec file. If in doubt post the complete output of both the freezing and your running application.
  • Please do not post pictures, but submit text. Pictures can not be searched nor quoted from.

• Software versions you are using.

  • version of Python If you are using some Python distribution (e.g. Anaconda), also describe this and give the version number or date.
  • exact version of PyInstaller (when using a git-checkout, please state the revision number)
  • exact version of the 3rd-party module trapping the error It's best to paste the download-URL. Again, if you are using a developer 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 are using Windows with Chinese, Japanese, or Korean languages, please be specific about this, due to complex Unicode issue around it.
  • 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 :-)

  • “Minimal“ means: remove everything from your code which is not relevant for this bug, esp. don't use external programs, remote requests, etc.
  • A very good example is https://gist.github.com/ronen/024cdae9ff2d50488438. This one helped us reproducing and fixing a quite complex problem within approx 1 hour.
  • For details how an example should look like see http://sscce.org/.

• 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 make sure to attach the log output generated by PyInstaller:

  1. Run the PyInstaller command and capture its output, as shown:

     pyinstaller [options] --log-level DEBUG > out.txt
     

  2. Upload out.txt to http://gist.github.com and note the link in the bug description.

• Please try latest development version and let us know if the bug is already fixed there. Simply use pip install https://github.com/pyinstaller/pyinstaller/archive/develop.zip to install the latest git version.

Errors specific to Windows

Errors that mention any of the following will indicate a problem with the bundling of Windows Side-by-side Assemblies with your built application:

• Side-by-side configuration is incorrect
• Error code 14001

To get more information about Windows Side-by-Side errors, please run the following commands in the Windows command shell and include the resulting trace.txt with your error report:

> sxstrace trace -logfile:trace.log
> (run your program here)
> (press ENTER to stop tracing)
> sxstrace parse -logfile:trace.log -outfile:trace.txt
> start trace.txt

Additional information about Side-by-side errors will be available in the Event Viewer, under the log Application, with the labels Error and SideBySide. Also include the information from the log entry if possible.

Thanks a lot!