Hartmut Goebel edited this page Jan 18, 2017 · 13 revisions

Frequently asked questions.


  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 Windows binaries while running under OS X?
      No, this is not supported. Please try Wine for this.
    3. 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.

  3. What file sizes can I expect for packaged binaries?
    Here are a few examples for Windows apps built with onefile:
    Python 2.7, "hello world" app: 3.3MB
    Python 3.4, "hello world" app: 4.9MB
    Python 2.7, medium sized app using PySide, numpy, PyOpenGL, and others: 27.4MB
    onefile apps are pretty slim, since they can compress the python libraries. onedir apps can be 50-100% larger. Many Python packages conditionally import some other packages. So to achieve slim apps it is recommended create a virtualenv with only dependencies required by your app.


  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 differentiate the bootloader from the builder?
      Just read the file COPYING.txt. All bootloader related files are in directories ./bootloader/ and ./PyInstaller/loader.


  1. What about .egg files?
    PyInstaller 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.

  2. 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). For details follow issue #183.

  3. If I make an executable with Pyinstaller, is it still possible to import new things that are on the PYTHONPATH?
    No and yes. PYTHONPATH is ignored, but you could evaluate it yourself and add the paths to sys.path. This is strongly discouraged, though, as it may lead to conflicts and thus problems which are very hard to track down.

  4. If I make an executable with Pyinstaller, how can I run another Python script?
    Q: I have created an executable with Pyinstaller. My program tries to run another Python script using subprocess.Popen(['python', 'myscript.py']) (or something like that). When I run the executable on a machine where python is not installed, I get an error like "command python is not recognised".
    A: You can not run an external Python script, as PyInstaller does not provide a python executable. You have some options to work around this: a) make an executable out of the other script, too, b) install Python on the target machine (in which case PyInstaller would be some kind of superfluous), or c) fork your program and run the other script in the forked process.


  1. 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 libpython.so 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.

  2. 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 ActivePython, Anaconda, Enthought Canopy, Python(x,y), WinPython or Pyzo may or may not work.

  3. 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:

Mac OS X

  1. 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:

    • MacPorts
    • Homebrew
    • pyenv
      • you would need to specify PYTHON_CONFIGURE_OPTS="--enable-shared" when building a Python version for PyInstaller
  2. 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.

  3. How to create application bundle (.app) on Mac OS X?
    The .app bundle is created automatically with the --windowed option.