Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/drake-rochelle/open-storefront/llms.txt

Use this file to discover all available pages before exploring further.

Open Storefront is a single Python script, which means anyone who wants to run it normally needs Python installed. By using PyInstaller you can bundle the script and all its dependencies into one self-contained executable that runs on Windows, macOS, or Linux with no Python installation required — making it much easier to distribute to end users.

​
Prerequisites

You need Python 3 and PyInstaller on the machine where you build the executable. The target machines that run the finished binary do not need Python at all.

​
Build Steps

1

Install PyInstaller

If you haven’t already, install PyInstaller into your Python environment:
pip install pyinstaller
2

Build the executable

From the directory containing main.py, run:
pyinstaller --onefile main.py
PyInstaller will analyse the script, collect dependencies, and produce a single bundled executable.
No custom .spec file is needed. The standard pyinstaller --onefile main.py command is sufficient — Open Storefront has no special bundling requirements beyond what PyInstaller handles automatically.
3

Find the output binary

After the build completes, the executable is placed in the dist/ subdirectory:
PlatformOutput path
Linux / macOSdist/main
Windowsdist/main.exe
You can rename and distribute this file freely.
4

Copy config files next to the binary

The executable looks for configuration files in the directory from which it is run. Copy any config files you want to ship alongside the binary:
cp download_path.txt dist/
cp home.3sf dist/
Neither file is required — the client runs without them using built-in defaults — but if you want to pre-configure a custom download path or a custom home storefront, the files must be present in the working directory when the binary is launched.

​
How It Works

When Python runs inside a PyInstaller bundle, the attribute sys.frozen is set to True. Open Storefront checks for this at startup: 
if getattr(sys, 'frozen', False):
    SCRIPT_DIR = Path(sys.executable).resolve().parent
else:
    SCRIPT_DIR = Path(__file__).resolve().parent
In frozen mode, SCRIPT_DIR resolves to the folder containing the executable rather than the original source file. The download_path.txt config file is looked up relative to SCRIPT_DIR, so it is found correctly regardless of where the user runs the binary from. Other files (home.3sf, input, and storefront.json) are opened using bare filenames, so they are resolved relative to the current working directory at runtime.

​
Config File Placement After Building

Once you have built and moved the binary out of the dist/ folder, keep config files co-located with it and run the binary from that same directory: 
my-storefront/
├── main.exe          ← the binary
├── download_path.txt ← optional: custom download directory (SCRIPT_DIR-relative)
└── home.3sf          ← optional: custom home storefront ID (CWD-relative)
Placing them anywhere else (such as the original source tree) will have no effect when running the compiled executable.
--onefile packages everything into a single executable, which is the easiest format to distribute — just share one file. If startup time is a concern (PyInstaller’s --onefile mode extracts to a temp directory on each launch), use --onedir instead to produce a folder of files that start faster. Distribute the whole folder in that case.
Many antivirus programs flag PyInstaller-produced executables as suspicious because of how they self-extract at runtime. This is a well-known false positive. If users report their antivirus blocking or quarantining the binary, advise them to add it to their antivirus whitelist or submit it for analysis to confirm it is safe.

Build docs developers (and LLMs) love

Get started for freeTalk to us