Package a PySide2 GUI application into a single-file executable with PyInstaller on Windows 11 and Ubuntu Linux 24.04. The app is the designer-built example from the QT-PySide2 project — a button that writes "Hello World!" into the text box — plus a release step that builds model/release/main (main.exe on Windows).
Important: PySide2 ships wheels for Python 3.7 to 3.10 only. Install one of those Python versions before running 01_venv_create; a newer Python needs the code ported to PySide6.
[Folder Structure]
- CLAUDE.md / AGENT.md: program specification (identical content).
- CHANGELOG.md: change log.
- copyright.txt: copyright notice.
- model/release/: the packaged executable produced by the build step.
- src/UI.ui: the Qt Designer layout file; src/UI.py is generated from it.
- src/: the app, release.py, the launcher scripts, and this document.
- venv/: Python virtual environment, created by step 1.
[Prerequisites]
- Operating system: Windows 11 or Ubuntu Linux 24.04.
- Python 3.7 to 3.10 — required by PySide2, which publishes no wheels for newer versions.
- Python packages: PySide2 and pyinstaller (installed automatically by step 1).
- A desktop environment, because the example opens a window. No GPU required.
- Ubuntu only, for Qt Designer: sudo apt install libqt5designercomponents5.
[Instructions]
Step 1: Create the virtual environment
Create the virtual environment and install src/requirements.txt (PySide2, pyinstaller). Make sure the active Python is version 3.7 to 3.10 first, or the PySide2 install will fail.
Windows 11:
src\01_venv_create.bat
Ubuntu Linux 24.04:
bash src/01_venv_create.sh
Step 2: Activate the virtual environment
Activate the environment in the current shell. On Linux you must source the script so the activation stays in effect after it finishes.
Windows 11:
src\02_venv_activate.bat
Ubuntu Linux 24.04:
source src/02_venv_activate.sh
Step 3: Open the layout in Qt Designer
Open src/UI.ui in Qt Designer to see or edit the window visually. This step is optional if you only want to run the existing example.
Windows 11:
src\03_open_designer.bat
Ubuntu Linux 24.04:
bash src/03_open_designer.sh
Step 4: Compile the layout into Python
Convert src/UI.ui into src/UI.py. Run this every time you change the layout in Designer — the application imports the generated .py file, not the .ui file.
Windows 11:
src\04_ui_to_py.bat
Ubuntu Linux 24.04:
bash src/04_ui_to_py.sh
Step 5: Run the application
Run the app from Python. A window opens; clicking the button writes "Hello World!" into the text box. Confirm it works here before packaging.
Windows 11:
src\05_run.bat
Ubuntu Linux 24.04:
bash src/05_run.sh
Step 6: Build the executable
Package the application with PyInstaller. The build produces a single-file executable at model/release/main (model/release/main.exe on Windows), which runs on a machine with no Python installed.
Windows 11:
src\06_release.bat
Ubuntu Linux 24.04:
bash src/06_release.sh
Step 7: Remove the virtual environment
When you are finished, delete the venv/ folder to free up disk space. Re-run step 1 whenever you need the environment again.
Windows 11:
src\99_venv_clear.bat
Ubuntu Linux 24.04:
bash src/99_venv_clear.sh
[Usage Notes]
- Linux with pip-installed PySide2: pyside2-designer needs a system Qt library the wheel does not bundle. sudo apt install libqt5designercomponents5 fixes the libQt5DesignerComponents.so.5 error. Running the application itself does not need it.
- PySide2 ships wheels for Python 3.7 to 3.10 only — install one of those Pythons before 01_venv_create; a newer Python needs a port to PySide6.
- Executables are per-OS: build on each target machine.
- The model/release/main.exe that ships with the SDK is the original 2022 Windows build; running step 6 replaces it with a fresh build.
- Edits made in Designer only take effect after step 4 regenerates src/UI.py.
This SDK is built in AppForAI - AI Dev Tools.
Purchase license separately: USD 600, permanent authorization, single APP authorization, single machine authorization, one-year activation, one-year download, one-year update, one-year email technical support.