If your programs alters Python import mechanism somehow (like many applications with plugins and extensions) you may run into problems with py2exe. This page is dedicated to explain the reasons for these problems and how to solve them. If you have an experience to share, please add your story here.

Check that zipextimporter works on your system

zipextimporter is the starting component of py2exe that may cause problems. To debug it you will need _memimporter.pyd binary module. These modules can be found in binary py2exe distributions for your Python version (I unpack .exe distribution with 7Zip). zipextimporter contains the following script to help with debugging using standard _socket.pyd module. Wrap _socket.pyd from your Python version into lib.zip and use the script to see that zipextimporter works ok.

   1 import zipextimporter
   2 zipextimporter.install()
   3 
   4 import sys
   5 sys.path.insert(0, "lib.zip")
   6 
   7 import _socket
   8 print _socket
   9 # <module '_socket' from 'lib.zip\_socket.pyd'>
  10 print _socket.__file__
  11 # 'lib.zip\\_socket.pyd'
  12 print _socket.__loader__
  13 # <ZipExtensionImporter object 'lib.zip'>
  14 # Reloading also works correctly:
  15 print _socket is reload(_socket)
  16 # True

Debugging compiled .exe with PY2EXE_VERBOSE

PY2EXE_VERBOSE is an environment variable that is understood by compiled .exe module. By setting this variable to 1 or 2 you can get verbose (or very verbose) log actions done by py2exe importer.

To get this debug log while using zipextimporter.py directly, you will need to insert this monkeypatching hack at the beginning of your test script:

   1 import zipextimporter
   2 zipextimporter.install()
   3 
   4 import _memimporter
   5 _memimporter.get_verbose_flag = lambda: 2
   6 
   7 # ...

Use debug version of zipextimporter.py with very verbose output

Attached zipextimporter-debug-0.6.9.py version understands value 3 of verbose flag of memimporter and can give a lot of useful output. Hope some parts can be committed to py2exe.