Fixing PyInstaller Startup Crash in Kivy App Using Python 3.10

Understanding Startup Crashes in Kivy Apps Built with PyInstaller

Building a Kivy app using PyInstaller is a common approach for packaging Python applications into standalone executables. However, despite a successful build process, developers sometimes encounter unexpected crashes when launching the packaged app. This issue can be particularly frustrating when no detailed error message is provided.

In this case, the app runs perfectly in the development environment, such as PyCharm, but fails when packaged using PyInstaller. With dependencies like Kivy 2.3.0, Python 3.10, and libraries like numpy, scipy, and pandas, identifying the source of the crash becomes critical for resolving the issue.

Errors like "unexpected error" with no clear trace often point to missing dependencies, incorrect SPEC file configurations, or virtual environment inconsistencies. Given the importance of ensuring all necessary files are correctly bundled, reviewing the PyInstaller SPEC file and runtime dependencies is a crucial step.

This article explores possible causes of the crash, focusing on improving your SPEC file, managing hidden imports, and ensuring that necessary Kivy dependencies are correctly handled during the build process.

Troubleshooting Kivy App Startup Errors with PyInstaller

The scripts provided above are focused on solving a very specific issue: a Kivy app built using PyInstaller crashing at startup with an "unexpected error." The first script addresses a potential problem with missing hidden imports. This is a common issue when using PyInstaller, as it does not automatically detect all dependencies, especially libraries like numpy, pandas, or scipy. By manually specifying these hidden imports in the Analysis section of the SPEC file, we ensure that PyInstaller bundles all necessary modules, preventing the app from crashing due to missing components.

The second important step in the script is the inclusion of Tree() in the COLLECT phase. This command ensures that the app's dependencies related to Kivy, such as the SDL2 and GLEW libraries, are correctly included in the build. These are essential for rendering the app’s graphical interface. If these files are not included, the Kivy app will fail to run properly, even though the build process completes without errors. Ensuring that these binaries are included helps avoid runtime issues related to missing graphics or sound components.

The script also addresses the inclusion of external files, such as a JSON file created by the JsonStore in Kivy. While this JSON file is generated at runtime, it is crucial to ensure that it is properly handled during the packaging process. The datas argument in the Analysis function allows us to explicitly include this file in the bundled app. By doing so, we avoid the error where the app crashes due to missing external data files during initialization.

Finally, we also see the use of UPX compression and the strip option. The UPX compression is used to reduce the size of the bundled application, making distribution easier. However, enabling UPX sometimes causes compatibility issues, which is why it is paired with strip=False to avoid removing debug symbols from binaries. By keeping the debug symbols, we can better trace the cause of any crashes or errors during runtime. Disabling windowed traceback is another configuration that helps in diagnosing issues, as it allows error messages to appear in the console, providing insights into potential issues at startup.

# Step 1: Modify the SPEC file to include hidden imports manually
# Import necessary dependencies from Kivy, sdl2, and glew
from kivy_deps import sdl2, glew
# Add numpy, pandas, scipy to hidden imports manually
a = Analysis([r'path_to_your_app.py'],
             pathex=['.'],
             binaries=[],
             datas=[],
             hiddenimports=['numpy', 'pandas', 'scipy'],
             hookspath=[],
             runtime_hooks=[],
             excludes=[],
             noarchive=False)
# Add Tree() for all Kivy dependencies to the collect step
coll = COLLECT(exe, Tree('C:\\path_to_project'),
               a.binaries, a.zipfiles, a.datas,
               *[Tree(p) for p in (sdl2.dep_bins + glew.dep_bins)],
               strip=False, upx=True, name='Prototype')

# Step 2: Ensure that the generated JSON file from kivy.storage.jsonstore is included
from kivy.storage.jsonstore import JsonStore
# If JSONStore is used, manually add the JSON file to the build
store = JsonStore('data.json')
# Create the SPEC file to explicitly include the JSON data
datas=[('data.json', '.')],
a = Analysis([r'path_to_your_app.py'],
             pathex=['.'],
             binaries=[],
             datas=[('data.json', '.')],
             hiddenimports=[],
             hookspath=[],
             runtime_hooks=[],
             excludes=[],
             noarchive=False)
coll = COLLECT(exe, Tree('C:\\path_to_project'),
               a.binaries, a.zipfiles, a.datas,
               *[Tree(p) for p in (sdl2.dep_bins + glew.dep_bins)],
               strip=False, upx=True, name='Prototype')

Optimizing PyInstaller for Kivy Apps to Prevent Startup Errors

When working with PyInstaller and Kivy, one key aspect to consider is the management of external dependencies and libraries. PyInstaller's default behavior sometimes overlooks certain libraries or files, especially when working with more complex setups like virtual environments or scientific libraries such as numpy and pandas. Ensuring that all hidden imports are specified in the hiddenimports parameter is critical. Additionally, PyInstaller may not automatically include graphical and multimedia dependencies such as those from sdl2 or glew, both of which are essential for Kivy apps.

Another aspect that developers often overlook is related to virtual environments. When building a Kivy app using PyInstaller within a virtual environment, it is important to ensure that all dependencies are bundled correctly. This involves adjusting the pathex setting to point to the correct directories where the libraries are installed. Failure to do so might result in the packaged app running fine in the development environment but crashing at startup in production. This problem can often be avoided by fully examining the build configuration and ensuring all paths and dependencies are correct.

Lastly, proper handling of resources such as images, fonts, and data files is crucial in preventing unexpected startup errors. In Kivy apps, external resources are frequently required, and if these are not explicitly included in the PyInstaller datas section, the app may crash during initialization when trying to access missing files. It's essential to verify that all files needed by the app at runtime are properly included in the final build.