Skip to main content

How to deploy / build .exe

This tutorial shows how to package Validrive as a single Windows executable so that any user can run it directly without needing to install Python or any dependencies.

NOTE: First complete How to set up and run (install Python, create the environment, and install dependencies).

1. Install the packaging tool​

For this project i use PyInstaller. It bundles a Python application and all its dependencies into a single package. The user can run the packaged app without installing a Python interpreter or any modules. PyInstaller supports Python 3.8 and newer.

Install it with the following command:

pip install pyinstaller

2. Build the executable​

From the project root (same folder as validrive.py), run the PyInstaller build. The following command is for PowerShell (uses backticks for line continuation):

pyinstaller --onefile --noconsole `
  --icon=logo_valid.ico `
  --splash=validrive_splash.png `
  --hidden-import pandas.plotting `
  --exclude-module matplotlib --exclude-module PIL --exclude-module pillow --exclude-module scipy --exclude-module IPython --exclude-module pygments --exclude-module tkinter `
  --add-data "style.qss;." --add-data "theme_dark.qss;." --add-data "theme_light.qss;." `
  --add-data "validrive_splash.png;." --add-data "arrow.png;." --add-data "mail.png;." --add-data "mail-black.png;." `
  --add-data "settings.png;." --add-data "sett_black.png;." --add-data "chromedriver.exe;." `
  validrive.py

3. What this command does​

  • --onefile: produce a single validrive.exe file. At runtime PyInstaller unpacks to a temp folder (exposed as sys._MEIPASS).
  • --noconsole: hide the console window (GUI-only app).
  • --icon=logo_valid.ico: sets the app icon.
  • --splash=validrive_splash.png: shows a native splash screen while the app initializes.
  • --hidden-import pandas.plotting: ensures pandas optional module is included (avoids lazy import misses).
  • --exclude-module ...: trims unused heavy modules to keep the .exe smaller.
  • --add-data ...: bundles styles and icons.

In the code, assets are accessed through resource_path(name), which maps to sys._MEIPASS in packaged mode. No path changes are needed between dev and packaged runs.

4. Where is the output?​

After a successful build, the executable is created at:

dist/validrive.exe

Double clickk to run it.

5. Troubleshooting​

  • Nothing happens when I run the EXE: ensure chromedriver.exe was included with --add-data and matches your installed Chrome version (or update the driver in How to replace ChromeDriver).
  • Large EXE size: verify the --exclude-module list and avoid bundling unnecessary libraries.
  • Console needed for debugging: temporarily remove --noconsole and rebuild to see stdout/stderr.