Gooey/docs/packaging/Packaging-Gooey.md

Packaging Gooey as a Stand Alone Application

⚠️ Packaging Gooey is an ongoing science. Gooey currently runs on all the major platforms, can be installed in a bajillion different ways, and has several active versions in wide usage. In short, edge cases abound. If you run into any problems, hit up this issue.

You can package all of your programs files into a single easy to distribute executable using PyInstaller.

Packing Gooey into a standalone executable is super straight forward thanks to PyInstaller. It is the only dependency you'll need and can be installed via the following.

pip install pyinstaller

Setting up the build:

PyInstaller uses spec files to determine how to bundle the project. These are a bit like setup.py files, but contain rules for how PyInstaller should bundle your whole application as a stand alone executable.

This file is usually placed in the root of your project. e.g.

MyProject/
   - src/
   - build.spec  # <-- goes here!
   - LICENCE.txt
   - README.md

Download Spec Files

• Windows users can grab a pre-built spec file here.
• For OSX users, you'll want this one.

The exact contents of the spec files will vary based on your OS, but at a high level, they'll share the same core pieces: Analysis, EXE, and, if you're on OSX, BUNDLE

# -*- mode: python ; coding: utf-8 -*-

block_cipher = None

a = Analysis(
    ['main.py'],  # replace me with the main entry point 
    pathex=['/path/to/main.py'],  # replace me with the appropriate path
    ...
    )

pyz = PYZ(a.pure)

options = [('u', None, 'OPTION'), ('v', None, 'OPTION'), ('w', None, 'OPTION')]

exe = EXE(pyz,
       ...
       name='MyCoolApplication'  # replace me with exe name
       console=False)
       
## OSX only below!       
app = BUNDLE(exe,
             name='APPNAME.app',  # osx users replace me!
             bundle_identifier=None,
             info_plist=info_plist
            )

The Analysis section is where you'll tell PyInstaller about your program. Using the build.spec from above, you'll need to make two edits to this section.

1. replace APPNAME in the Analysis() section with the name of your application
2. replace the pathex value in the Analysis() section with the path to your application's root

note: If you use additional data resources (e.g. images, data, etc..) you'll also need to explicitly add them to the EXE section. See [packaging custom images] for more info.

Next is EXE. In this section you'll replace the name argument with what you'd like the final .exe to be named.

Note: if you're providing your own icon file, EXE is where you'll provide it. If you're on Windows, you must provide an .ico file (not PNG).

If you're on OSX, you'll have an additional BUNDLE section. You'll need to make one final edit here as well to control the name of the .app bundle that PyInstaller produces. Additionally, if you're customizing the bundle's icon, this is where you would supply the override (versus Windows, which places it in the EXE section).

Once you've updated the .spec to reflect your program's details. All that's left to do is build the executable!

Running the .spec file

From the command line, run

pyinstaller -F --windowed build.spec

• -F tells PyInstaller to create a single bundled output file
• --windowed disables the terminal which would otherwise launch when you opened your app.

And that's it. Inside of the dist/ directory, you'll find a beautiful stand-alone executable that you can distribute to your users.

Troubleshooting

PROBLEM: My bundled Application won't work!

First things first: See if you can package your application without Gooey!

Read and understand all of the PyInstaller docs. If you're referencing binaries or external data files, you may have to do a little extra work in your .spec to get PyInstaller to understand all of your dependencies.

Rebuild your bundle with debug=True set in the .spec file. This will give lots of useful output when your application bootstraps which can make pinning down the problem much easier.

Rebuild your bundle without the -F flag (e.g. just pyinstaller build.spec). This will build a directory with all of your dependencies. This can make it easier to poke around and see what PyInstaller's view of your project actually is.

PROBLEM: I'm seeing the wrong icon on my executable

First things first: Is Windows gas lighting you?

Windows caches icons semi-aggressively. This can lead to it showing an icon in the file explorer that doesn't actually reflect reality.

Right-click on the executable and select "properties." This will show you the icon that's actually associated with file. As long as everything looks good there, you're golden. Windows will catch up... eventually.

PROBLEM: Exception: This program needs access to the screen. Please run with a Framework build of python, and only when you are logged in on the main display of your Mac.

This happens on OSX when you neglect the --windowed flag during your build step.

wrong:

pyinstaller build.spec  ## oops! forgot the required flags    

Correct:

pyinstaller --windowed build.spec 

Checkout the Pyinstaller Manual for more details.