CRM Build

Stage 04 · Desktop

Home › Apps › CRM › Stage 04
🖥️ Stage 04 · 2–3 hours

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.

2–3 hours Intermediate Python · PySide6 · SQLite · PyInstaller
CRM hub Why desktop The widgets Packaging Full project

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.

main.py
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.

terminal
# 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.

Files to save:
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:

folder structure
crm-stage-04/
├── main.py
├── database.py
├── schema.sql
├── seed.py
├── requirements.txt
└── README.md

Option B: Recreate the folder in one command

terminal
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

terminal
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.

1. Packaging before the source works

The executable inherits every bug. Fix: python main.py must open the app before pyinstaller.

2. Forgetting --add-data "schema.sql:."

The app crashes on launch: schema.sql not found. Fix: include it, or use --add-data "schema.sql;." on Windows.

3. Relative paths in the packaged app

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.

4. Trying to run a .exe on macOS

Builds are per-platform. Fix: build on each platform. Or use a CI service with a matrix.

5. Missing --windowed

A terminal opens behind the app. Fix: add --windowed (or -w).

6. PySide6 not installed

pip install -r requirements.txt was skipped. Fix: activate the venv and install.

7. Code signing errors on macOS

The app won't open ("damaged"). Fix: right-click → Open, or sign with an Apple certificate for public distribution.

8. The packaged app is 100MB+

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.

🗺️ Back to the CRM build hub
Review all four stages
🖥️ All applications
See the full app gallery
← Back to CRM build hub
CRM Stage 04 · Desktop