Ship it as a desktop app.
PySide6 + PyInstaller.
The final stage. Rebuild the CRM as a native desktop application with PySide6 — the official Python bindings for Qt. Then package it as a standalone executable with PyInstaller: a single file that runs on any machine, no Python installation required. This is the journey from an empty HTML file to a shipped product.
Short answer: Five Python files. A QMainWindow with a table, a header row, four KPI cards, and filter chips. A QDialog for add/edit. SQLite for storage. Packaged with pyinstaller --onefile --windowed --add-data "schema.sql:." main.py. The result is a single executable that runs on Windows, macOS, or Linux. No Python, no server, no browser.
✅ Why ship a desktop app
The web version works. What does desktop add?
No browser, no server
The app runs on its own. No localhost:5000, no terminal, no Flask. Just double-click and go.
Native performance
Qt renders natively — no DOM, no CSS engine, no JavaScript VM. For a data-heavy table, it's smoother.
Real file system access
The app can read and write files, use the clipboard, show native dialogs — without browser permissions.
Works offline, always
No network needed. The SQLite database is a local file. The app is fully self-contained.
Distributable
One executable. Ship it on a USB stick, a download link, or an enterprise installer. No dependencies.
Different UI paradigm
Qt uses signals/slots, model/view, and native widgets. A genuinely new toolkit to learn.
✅ The widgets
From web components to Qt widgets.
from PySide6.QtWidgets import ( QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout, QLabel, QLineEdit, QPushButton, QTableWidget, QTableWidgetItem, QDialog, QComboBox, QTextEdit, ) class MainWindow(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle("MAK CRM") self.setMinimumSize(1100, 700) central = QWidget() self.setCentralWidget(central) layout = QVBoxLayout(central) # Header: title + search + add button header = QHBoxLayout() header.addWidget(QLabel("Dashboard")) header.addStretch() self.search_input = QLineEdit() self.search_input.textChanged.connect(self.refresh_table) header.addWidget(self.search_input) add_btn = QPushButton("+ Add Customer") add_btn.clicked.connect(self.add_customer) header.addWidget(add_btn) layout.addLayout(header) # Table: name, company, email, status, actions self.table = QTableWidget() self.table.setColumnCount(6) self.table.setHorizontalHeaderLabels([ "Name", "Company", "Email", "Status", "Added", "Actions" ]) layout.addWidget(self.table)
The mental map:
HTML Qt
───────────────────── ─────────────────────
<div> QWidget
<h1> QLabel
<input> QLineEdit
<select> QComboBox
<textarea> QTextEdit
<button> QPushButton
<table> QTableWidget
<dialog> QDialog
flexbox layout QVBoxLayout / QHBoxLayout
CSS grid QGridLayout
addEventListener('click') button.clicked.connect(fn)
textContent = 'x' label.setText('x')
document.createElement QWidget()
appendChild layout.addWidget()
The pattern is the same:
state → render() → event → state
In Stage 02:
state.customers → renderTable() → click → addCustomer() → renderTable()
In Stage 04:
self.current_filter → refresh_table() → clicked.connect → add_customer() → refresh_table()
The state is Python instance attributes.
The render is refresh_table().
The events are signal/slot connections.
What's different in Qt:
1. Signals and slots
Instead of addEventListener, you connect
a signal (clicked, textChanged) to a slot
(a Python function).
button.clicked.connect(self.handle_click)
The slot is called when the signal fires.
No manual event object. No event.target.
The handler knows what it's attached to.
2. Layouts, not CSS
Layouts are objects (QVBoxLayout).
Add widgets to a layout with addWidget.
Nested layouts compose (a QVBoxLayout with
QHBoxLayouts inside it).
No position, no flex, no grid-template.
The layout does the geometry automatically.
3. Widgets are classes
To customize behavior, subclass the widget
and override its methods.
To customize appearance, use a stylesheet
(which is CSS-like but with Qt selectors).
QPushButton { background: #61dafb; }
Qt stylesheets are more limited than CSS
(no calc, no flex, no grid), but they work
for colors, borders, padding, fonts.
4. State lives on the object
self.current_filter = "all"
self.search_input = QLineEdit()
Python instance attributes. No global
state object. The window owns its state.
The event flow:
User types in search:
QLineEdit.textChanged fires
→ self.refresh_table() is called
→ fetches customers
→ filters by search text
→ repopulates self.table
User clicks "Add":
QPushButton.clicked fires
→ self.add_customer() is called
→ opens CustomerDialog
→ on save: insert_customer(data)
→ self.refresh_table()
User clicks "Edit" on a row:
QPushButton.clicked fires (per-row button)
→ self.edit_customer(id) is called
→ opens CustomerDialog with data
→ on save: update_customer(id, data)
→ self.refresh_table()
Same flow as the web. Different names.
✅ Packaging with PyInstaller
One command. One executable.
# 1. Verify the app runs from source first python main.py # 2. Install PyInstaller pip install pyinstaller # 3. Build the executable pyinstaller --onefile --windowed --name "MAK CRM" \ --add-data "schema.sql:." \ main.py # On Windows, use ; instead of : in --add-data pyinstaller --onefile --windowed --name "MAK CRM" ^ --add-data "schema.sql;." ^ main.py # 4. Find the executable # Windows: dist/MAK CRM.exe # macOS: dist/MAK CRM.app # Linux: dist/MAK CRM
The flags explained:
--onefile
Bundle everything into a single file.
Without it, PyInstaller produces a folder
with the executable plus the dependencies
(Qt libraries, Python runtime, etc.).
--onefile: one file, starts a bit slower
(unpacks to a temp dir on launch)
folder mode: many files, starts faster
For a simple app, --onefile is the right
choice. For a production app, folder mode
is often preferred (faster startup, easier
code signing).
--windowed (or -w)
Hide the terminal console window.
Without it, the app opens with a black
terminal window behind it. On macOS,
--windowed is automatic.
--name "MAK CRM"
Sets the output filename.
Without it, the name defaults to the
script name (main).
The spaces in the name work on macOS
and Linux. On Windows, PyInstaller
produces MAK CRM.exe with a space
in the name — works fine.
--add-data "schema.sql:."
Bundle schema.sql into the executable.
The format is source:destination.
On Windows, use ; instead of :.
The . destination means "put it next
to the executable in the temp unpack
directory." That's where database.py
looks for it (via sys._MEIPASS
resolution in the code).
What PyInstaller does:
1. Analyzes main.py
2. Follows the imports
- PySide6 (the whole Qt library)
- database.py
- schema.sql (bundled via --add-data)
3. Collects every .py, .so/.dylib/.dll,
and data file into the executable
4. Adds a small bootstrap that:
- Unpacks everything to a temp dir
- Runs Python with the bundled interpreter
- Starts the app
The result:
A single file that runs on any machine
with the same operating system.
Cross-platform:
A .exe built on Windows runs on Windows.
A .app built on macOS runs on macOS.
A Linux binary built on Linux runs on Linux.
To support multiple platforms:
Build on each platform (a Windows VM,
a Mac, a Linux box) — or use a CI service
like GitHub Actions with a matrix of
operating systems.
Code signing:
On Windows, unsigned .exe files trigger
SmartScreen warnings.
On macOS, unsigned .app files trigger
Gatekeeper.
For personal use or a small team, click
through the warnings.
For public distribution, buy a code
signing certificate and sign the executable.
This is beyond Stage 04's scope. PyInstaller
produces a working executable; signing is
a deployment concern.
Debugging the build:
If the executable crashes on launch:
- Run it from a terminal to see the error:
./"MAK CRM" (macOS/Linux)
"MAK CRM.exe" (Windows)
- The most common cause is a missing
--add-data (schema.sql not found).
- Check dist/ for the executable and any
warnings printed during the build.
To see what PyInstaller bundled:
pyinstaller --onefile --windowed \
--name "MAK CRM" \
--add-data "schema.sql:." \
--log-level DEBUG \
main.py
The debug log shows every file collected.
Don't skip the "runs from source" step. If python main.py doesn't open the app and show the customers, pyinstaller won't fix it — it will just produce a broken executable. The order is: (1) the app runs from source, (2) then package. Debugging a PyInstaller build is much harder than debugging the source. Get the source working first, then package.
✅ The full project
Six files. Copy them or recreate them.
Stage 04 is a folder with 5 Python files (plus the README). Copy each file to the exact path shown, or run the script at the bottom to recreate the structure in one command.
| Path | Purpose |
|---|---|
| main.py | PySide6 app: window, dialog, table |
| database.py | SQLite helpers |
| schema.sql | The customers table |
| seed.py | Sample data loader |
| requirements.txt | PySide6, pyinstaller |
| README.md | Setup and packaging instructions |
Option A: Save each file manually
Each file is in a code block above (Files 1–6). Save each one to the path in the table. The folder structure must be:
crm-stage-04/ ├── main.py ├── database.py ├── schema.sql ├── seed.py ├── requirements.txt └── README.md
Option B: Recreate the folder in one command
mkdir crm-stage-04 cd crm-stage-04 touch main.py database.py schema.sql seed.py requirements.txt README.md echo "Folder created. Paste the code from each block above into the matching file." ls
Run and package
cd crm-stage-04 python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt python seed.py python main.py # the app should open # When the app works, package it: pyinstaller --onefile --windowed --name "MAK CRM" \ --add-data "schema.sql:." \ main.py # Windows: use ; instead of : in --add-data # The executable is at dist/MAK CRM.exe (or .app, or binary)
Native window
The app opens as a normal desktop window, not a browser tab. Native menus, native dialogs.
Self-contained
The packaged executable bundles Python and PySide6. No dependency installation on the target machine.
Cross-platform
Build on Windows for Windows, on macOS for macOS, on Linux for Linux. Same source code.
Ship it
One file. USB stick, download link, email attachment, enterprise installer. It runs.
⚠️ Common mistakes
What to check if the app or the build fails.
The executable inherits every bug. Fix: python main.py must open the app before pyinstaller.
--add-data "schema.sql:."The app crashes on launch: schema.sql not found. Fix: include it, or use --add-data "schema.sql;." on Windows.
Files aren't found because the working directory is different. Fix: use sys._MEIPASS in the packaged app. The database.py file already handles this.
Builds are per-platform. Fix: build on each platform. Or use a CI service with a matrix.
--windowedA terminal opens behind the app. Fix: add --windowed (or -w).
pip install -r requirements.txt was skipped. Fix: activate the venv and install.
The app won't open ("damaged"). Fix: right-click → Open, or sign with an Apple certificate for public distribution.
Qt is a large library. Fix: this is normal. Use folder mode (no --onefile) for smaller total size, or exclude unused Qt modules with --exclude-module.
❓ Frequently asked
What will I build in Stage 04?
A native desktop CRM application built with PySide6 — the official Python bindings for Qt. It looks and behaves like a normal desktop app: a window with a table, a modal dialog for add/edit, native buttons and dropdowns. The data is stored in a local SQLite database. The whole app is packaged as a single executable file with PyInstaller, so anyone can double-click it and run it.
Why rebuild the UI instead of wrapping the web version?
You could wrap the web version with Electron or Tauri. That works. But it doesn't teach anything new: the same web code, in a different frame. PySide6 rebuilds the UI in Qt, which is a genuinely different toolkit. Rebuilding the UI in Qt teaches you how desktop frameworks think — the model/view pattern, the signal/slot system, the widget hierarchy.
What is the model/view pattern in Qt?
It's the Qt equivalent of state → render. In Stage 02, you had a state object and a render() function. In Qt, you have a data model and a view (a QTableWidget) that displays it. When the data changes, you call refresh_table(), which clears the view and repopulates it. Same pattern, different names.
Why PyInstaller and not cx_Freeze or Nuitka?
PyInstaller is the most widely used and best-documented tool for packaging Python apps. It supports Windows, macOS, and Linux, handles PySide6 out of the box, and produces a single executable with --onefile. For a first desktop app, it's the right tool.
How large is the packaged app?
Around 80–120 MB, depending on the platform and PySide6 version. Qt is a large library — the packaged app includes the Qt runtime, the platform plugins, and the Python interpreter. This is normal for Qt desktop apps. Electron apps are typically 100–150 MB, so Qt is competitive.
Can I share the executable with someone who doesn't have Python?
Yes. That's the whole point of PyInstaller. The executable bundles Python, PySide6, and your code into a single file. The recipient double-clicks it and the app runs. The only requirement is the same operating system: a Windows .exe doesn't run on macOS, and a macOS .app doesn't run on Windows.
🎉 CRM build complete
You've built the CRM end-to-end: interface → interactions → backend → desktop. Four stages, four working apps, one complete project. The same pattern — state → render → event — powers all four. The same data model — customers, statuses, timestamps — persists through all four. The same discipline — escape user data, validate at the boundary, handle errors — applies to all four.