label_printer/PYINSTALLER_GUIDE.md

Building a Standalone EXE with PyInstaller

This guide explains how to create a standalone Windows executable (.exe) file that doesn't require Python to be installed.

Quick Start (Windows)

Prerequisites

• Python 3.11+ installed
• Virtual environment activated
• All dependencies installed

One-Command Build

# Activate virtual environment
venv\Scripts\activate

# Build the executable
python build_exe.py

That's it! Your executable will be in dist/LabelPrinter.exe

---

What Happens During Build

1. Analyzes your code - Finds all imported modules
2. Collects dependencies - Bundles Kivy, PIL, barcode, reportlab, etc.
3. Creates executable - Packages everything into one .exe file
4. Output: dist/LabelPrinter.exe (~150-200 MB)

---

Detailed Build Instructions

Step 1: Install PyInstaller

venv\Scripts\activate
pip install pyinstaller

Step 2: Build Using Script

python build_exe.py

Step 3: Alternative Manual Build

If the script doesn't work, use this command directly:

pyinstaller ^
  --onefile ^
  --windowed ^
  --name=LabelPrinter ^
  --hidden-import=kivy ^
  --hidden-import=kivy.core.window ^
  --hidden-import=kivy.core.text ^
  --hidden-import=kivy.core.image ^
  --hidden-import=kivy.uix.boxlayout ^
  --hidden-import=kivy.uix.gridlayout ^
  --hidden-import=kivy.uix.label ^
  --hidden-import=kivy.uix.textinput ^
  --hidden-import=kivy.uix.button ^
  --hidden-import=kivy.uix.spinner ^
  --hidden-import=kivy.uix.scrollview ^
  --hidden-import=kivy.uix.popup ^
  --hidden-import=kivy.clock ^
  --hidden-import=kivy.graphics ^
  --hidden-import=PIL ^
  --hidden-import=barcode ^
  --hidden-import=reportlab ^
  --hidden-import=print_label ^
  --hidden-import=print_label_pdf ^
  --collect-all=kivy ^
  --collect-all=PIL ^
  label_printer_gui.py

---

Output Files

After building, you'll have:

Label-design/
├── dist/
│   └── LabelPrinter.exe          ← Your standalone executable (150-200 MB)
├── build/                         ← Temporary build files (can delete)
└── label_printer.spec             ← PyInstaller spec file

---

Running the Executable

On Your Computer

1. Double-click dist/LabelPrinter.exe
2. App starts immediately (first run takes ~5 seconds)
3. Works like the Python version

Sharing with Others

1. Copy dist/LabelPrinter.exe to a folder
2. Create a shortcut to it on the desktop
3. Share the folder or executable
4. No Python installation needed on their computer!

Creating a Shortcut

1. Right-click LabelPrinter.exe
2. Send to → Desktop (create shortcut)
3. Double-click the shortcut to run

---

Troubleshooting

"Failed to build the executable"

Solution 1: Check Python version

python --version  # Should be 3.11+

Solution 2: Update PyInstaller

pip install --upgrade pyinstaller

Solution 3: Install missing dependencies

pip install -r requirements_windows.txt
pip install pyinstaller

"DLL load failed" when running exe

This usually means a library isn't bundled correctly.

Solution: Rebuild with verbose output

pyinstaller --debug=imports label_printer_gui.py

Executable is very large (200+ MB)

This is normal for Kivy applications. The size includes:

• Python runtime (~50 MB)
• Kivy framework (~30 MB)
• Dependencies (PIL, barcode, reportlab, etc.) (~20 MB)
• Your code (~1 KB)

You can reduce size slightly with:

--exclude-module=matplotlib
--exclude-module=numpy
--exclude-module=scipy

Slow to start (5-10 seconds)

Normal for Kivy apps. The first startup initializes:

• Python runtime
• Kivy graphics system
• Font rendering
• Window initialization

Subsequent runs are faster (~3 seconds).

---

Advanced Options

Add an Icon

1. Create a 256x256 PNG icon: app_icon.png
2. Convert to ICO: Use an online tool or ImageMagick
3. Build with icon:

pyinstaller --icon=app_icon.ico label_printer_gui.py

Two-File Distribution

Instead of --onefile, use separate files for faster startup:

pyinstaller label_printer_gui.py

Creates dist/ folder with all files (faster to run, easier to debug).

Console Output

To see error messages, remove --windowed:

pyinstaller --onefile --name=LabelPrinter label_printer_gui.py

---

Build Options Reference

Option	Purpose
--onefile	Single executable (recommended)
--windowed	No console window
--icon=file.ico	Custom icon
--hidden-import=module	Include module that's not imported directly
--collect-all=module	Include all module data
--distpath=folder	Output directory
--name=AppName	Executable name

---

Final Steps

1. Test the executable: Run LabelPrinter.exe and test all features
2. Verify PDF backup: Check pdf_backup/ folder is created
3. Test printing: Print a label to ensure PDF output works
4. Share: Distribute the .exe file to users

---

Questions?

• Check the error message in the console
• Try rebuilding with python build_exe.py
• Ensure all dependencies are installed: pip install -r requirements_windows.txt
• Check that Python 3.11+ is installed: python --version

Good luck! 🚀