The complete PySide2 + Qt Designer workflow on Windows 11 and Ubuntu Linux 24.04: design the window visually in Qt Designer, compile the layout into Python with pyside2-uic, and run the application — a button that writes "Hello World!" into a text box. This is the pattern to follow whenever a Qt window is easier to draw than to hand-code.
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.
- src/UI.ui: the Qt Designer layout file — the one you edit.
- src/UI.py: the Python code generated from UI.ui by step 4 — do not edit it by hand.
- src/: the application, 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 (installed automatically by step 1).
- A display is required, because the example opens a window. No GPU needed.
- 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). 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: Design the window in Qt Designer
Open src/UI.ui in Qt Designer. Drag widgets onto the window, set their names and properties, and save. The names you give the widgets here are the names the Python code uses, so keep them meaningful.
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 with pyside2-uic. 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. A window opens; clicking the button writes "Hello World!" into the text box. Close the window to end the program.
Windows 11:
src\05_run.bat
Ubuntu Linux 24.04:
bash src/05_run.sh
Step 6: 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.
- The designer and uic helpers locate the tools with shutil.which, so the same scripts work on both operating systems.
- Never edit src/UI.py by hand: step 4 overwrites it. Put your own code in the application file and leave the generated layout alone.
- Edits made in Designer only take effect after step 4 regenerates src/UI.py — if a change does not show up, that step was skipped.
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.