Python GUIs - deployment

Deploying PyQt6 Apps on macOS with py2app — How to package your PyQt6 application into a standalone macOS .app bundle

2021-04-09T09:00:00+00:00

I've got my PyQt app working, but when I try to build it into a macOS .app bundle using py2app, the resulting application crashes on launch with "quit unexpectedly." I've stripped my code down to the bare minimum — it just loads a .ui file and displays a window — but the built app still won't run. What's the easiest way to deploy a PyQt application on a Mac?

If you've ever spent days wrestling with packaging tools only to get a crash on launch, you're not alone. Getting a PyQt app running in your editor is one thing; turning it into a distributable macOS application is a different challenge entirely. The good news is that py2app works well once you understand a few common stumbling blocks — especially around Python environments and .ui files.

This guide walks you through deploying a PyQt6 application on macOS using py2app, step by step.

Why Does py2app Crash? The Anaconda Problem

One of the most common causes of mysterious py2app crashes is building from an Anaconda environment. Anaconda bundles its own copies of many libraries and has a complex environment structure that py2app doesn't always handle correctly. The result is an app that builds without errors but crashes immediately when you try to open it.

The fix is straightforward: use a standard Python virtual environment instead of Anaconda when building your app.

Setting Up a Clean Virtual Environment

Start by creating a fresh virtual environment using Python's built-in venv module. Open a terminal and run:

bash

python3 -m venv myapp_env
source myapp_env/bin/activate

Now install the packages your application needs:

bash

pip install PyQt6 py2app

This gives you a clean, minimal Python environment — exactly what py2app needs to correctly identify and bundle your dependencies.

Preparing Your Application

Let's work with a simple example application. Here's a minimal PyQt6 app that loads a .ui file created in Qt Designer:

python

import sys
from PyQt6 import QtWidgets as qtw
from PyQt6 import uic


Ui_MainForm, baseClass = uic.loadUiType("mainwindow.ui")


class MainWindow(baseClass):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.ui = Ui_MainForm()
        self.ui.setupUi(self)

        self.show()


if __name__ == "__main__":
    app = qtw.QApplication(sys.argv)
    w = MainWindow()
    sys.exit(app.exec())

Make sure this runs correctly from the command line before you try to package it:

bash

python main.py

If the window shows up, you're ready to package.

Creating the setup.py File

py2app uses a setup.py file to know how to build your application. You can generate a starter one automatically:

bash

py2applet --make-setup main.py

This creates a basic setup.py. However, you'll need to edit it to include your .ui file. Open setup.py and make sure it looks something like this:

python

from setuptools import setup

APP = ["main.py"]
DATA_FILES = ["mainwindow.ui"]
OPTIONS = {
    "argv_emulation": False,
    "packages": ["PyQt6"],
}

setup(
    app=APP,
    data_files=DATA_FILES,
    options={"py2app": OPTIONS},
    setup_requires=["py2app"],
)

There are a few things to note here:

DATA_FILES must include your .ui file. If py2app doesn't bundle it, your app will crash at runtime because it can't find the file.
"packages": ["PyQt6"] tells py2app to include the entire PyQt6 package. Without this, py2app sometimes misses Qt plugins or submodules, leading to crashes.
"argv_emulation": False avoids a known issue on newer versions of macOS where argv emulation can cause launch failures.

Building the Application

First, test with alias mode. This creates an app bundle that links back to your source files rather than copying them — useful for quick testing:

bash

python setup.py py2app -A

Open the generated .app file from the dist/ folder:

bash

open dist/main.app

If that works, build the full standalone version:

bash

python setup.py py2app

This takes longer because py2app is copying Python, PyQt6, Qt libraries, and all dependencies into the app bundle. When it finishes, you'll find the distributable .app in the dist/ folder.

Handling .ui Files at Runtime

There's a subtlety with .ui files that catches a lot of people out. When your app runs from a .app bundle, the working directory isn't what you might expect. The .ui file is bundled inside the app, but uic.loadUiType("mainwindow.ui") looks for it relative to the current working directory, which may not be where the file actually is.

To make your .ui file loading work both during development and inside a packaged app, use a path relative to the script's location:

python

import os
import sys
from PyQt6 import QtWidgets as qtw
from PyQt6 import uic

# Get the directory where this script (or frozen app) lives
if getattr(sys, "frozen", False):
    # Running inside a py2app bundle
    basedir = os.path.dirname(sys.executable)
    # Data files are in ../Resources relative to the executable
    basedir = os.path.join(basedir, "..", "Resources")
else:
    basedir = os.path.dirname(os.path.abspath(__file__))

ui_path = os.path.join(basedir, "mainwindow.ui")
Ui_MainForm, baseClass = uic.loadUiType(ui_path)


class MainWindow(baseClass):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.ui = Ui_MainForm()
        self.ui.setupUi(self)

        self.show()


if __name__ == "__main__":
    app = qtw.QApplication(sys.argv)
    w = MainWindow()
    sys.exit(app.exec())

When py2app bundles your application, data files listed in DATA_FILES end up in the Contents/Resources directory inside the .app bundle. The code above accounts for this by checking sys.frozen — an attribute that py2app sets when your code is running inside a bundle.

An Alternative: Skip .ui Files Entirely

Another approach that avoids file-path issues altogether is to convert your .ui file to Python code before packaging. You can do this with the pyuic6 tool:

bash

pyuic6 mainwindow.ui -o ui_mainwindow.py

Then import the generated module directly:

python

import sys
from PyQt6 import QtWidgets as qtw
from ui_mainwindow import Ui_MainWindow


class MainWindow(qtw.QMainWindow, Ui_MainWindow):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setupUi(self)
        self.show()


if __name__ == "__main__":
    app = qtw.QApplication(sys.argv)
    w = MainWindow()
    sys.exit(app.exec())

With this approach, py2app treats the UI as regular Python code — no data files to worry about, no path issues. This is generally the most reliable approach for packaging. For more on designing interfaces with Qt Designer, see our tutorial on using Qt Designer with PyQt6.

Troubleshooting Checklist

If your built app crashes on launch, work through this list:

Use a clean virtual environment. Don't build from Anaconda or conda. Create a fresh venv, install only what you need, and build from there.

Include all data files. Any file your application loads at runtime — .ui files, images, config files — must be listed in DATA_FILES in your setup.py.

Include the full PyQt6 package. Add "packages": ["PyQt6"] to your py2app options to avoid missing submodules or Qt plugins.

Disable argv emulation. Set "argv_emulation": False in your options. This feature is known to cause problems on recent macOS versions.

Check the crash log. When an app crashes, macOS generates a crash report. Look for Python tracebacks or missing library errors — they often point directly at the problem.

Run from the terminal for output. Instead of double-clicking the .app, run the executable directly to see error messages:

bash

./dist/main.app/Contents/MacOS/main

This prints any Python exceptions to the terminal, which is far more useful than a macOS crash dialog.

If you'd like to explore other packaging approaches, you may also want to look at packaging PyQt6 applications with PyInstaller on macOS, which can create .dmg installers.

Complete Working Example

Here's everything together. This example converts the .ui file to Python to avoid path issues, which is the most reliable approach for packaging.

setup.py:

python

from setuptools import setup

APP = ["main.py"]
DATA_FILES = []
OPTIONS = {
    "argv_emulation": False,
    "packages": ["PyQt6"],
}

setup(
    app=APP,
    data_files=DATA_FILES,
    options={"py2app": OPTIONS},
    setup_requires=["py2app"],
)

main.py:

python

import sys
from PyQt6 import QtWidgets as qtw
from ui_mainwindow import Ui_MainWindow


class MainWindow(qtw.QMainWindow, Ui_MainWindow):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setupUi(self)
        self.show()


if __name__ == "__main__":
    app = qtw.QApplication(sys.argv)
    w = MainWindow()
    sys.exit(app.exec())

Build commands:

bash

python3 -m venv build_env
source build_env/bin/activate
pip install PyQt6 py2app
pyuic6 mainwindow.ui -o ui_mainwindow.py
python setup.py py2app

Your finished .app bundle will be in the dist/ folder, ready to share. Deploying PyQt6 apps on macOS does take a bit of setup, but once you have a working recipe like this, you can reuse it for all your projects. If you're new to PyQt6, our guide to creating your first window is a great place to start before diving into packaging.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Linux Packaging Preferred Formats for Python GUI Applications — Choosing the right packaging format for distributing your Python apps on Linux

2020-08-05T09:00:00+00:00

What packaging format should I use to distribute my Python GUI application to Linux users? Options like .deb, Snap, AppImage, and others all exist — which ones do users actually prefer?

If you've built a Python GUI application and you're ready to share it with Linux users, one of the first questions you'll face is: how do I package this thing? Linux doesn't have a single, universal installer format the way Windows has .exe or macOS has .dmg. Instead, there's a whole landscape of packaging options, each with its own strengths, trade-offs, and fan base.

The short answer is: it depends on your audience. But let's walk through the most common formats so you can make an informed decision.

Distribution-Specific Packages: `.deb` and `.rpm`

The most traditional way to distribute software on Linux is through the native package format for a given distribution family.

.deb files are used by Debian, Ubuntu, Linux Mint, and their many derivatives. This is the largest desktop Linux user base, and .deb is a familiar, trusted format for those users.
.rpm files are used by Fedora, Red Hat, openSUSE, and related distributions.
Arch Linux and its derivatives (like Manjaro) use PKGBUILD scripts and the AUR (Arch User Repository), which is a different approach entirely — users build packages from source descriptions rather than downloading prebuilt binaries.

Distribution-specific packages integrate well with the system. They're installed via the system package manager (apt, dnf, pacman), which handles dependencies, updates, and removal cleanly. Users tend to trust and prefer these formats because they feel native.

The downside is obvious: you need to create and maintain separate packages for each distribution family you want to support. If your audience is primarily on Ubuntu and Mint, a .deb file is a great choice. If you need to reach Fedora users too, you'll also want an .rpm. And Arch users will expect something different again.

Cross-Distribution Formats: AppImage, Snap, and Flatpak

To address the fragmentation problem, several "universal" packaging formats have emerged. These aim to work across distributions without needing separate builds for each one.

AppImage

An AppImage is a single executable file that bundles your application and all its dependencies. Users download it, make it executable (chmod +x), and run it. There's no installation step.

Pros: - Simple for users — just download and run. - No root access needed. - No system-wide changes. - Works on most distributions.

Cons: - No automatic updates (unless you build that in). - No integration with the system package manager. - Can result in large file sizes since everything is bundled. - Some users and distributions are wary of software that lives outside the package manager.

Snap

Snap is a packaging format developed by Canonical (the company behind Ubuntu). Snaps are distributed through the Snap Store and run in a sandboxed environment.

Pros: - Automatic updates. - Sandboxing provides some security isolation. - Available on many distributions (though Ubuntu has the deepest integration).

Cons: - The Snap daemon (snapd) must be installed, and not all distributions include it by default. - Snap applications can be slower to launch due to the sandboxing and compression. - Some parts of the Snap infrastructure are proprietary, which is a philosophical issue for some Linux users and communities. Notably, some distributions (like Linux Mint) have taken steps to discourage or block Snap.

Flatpak

Flatpak is similar in concept to Snap but is community-driven and uses Flathub as its main repository.

Pros: - Sandboxed applications. - Widely supported across distributions. - Community-governed, which appeals to users who prefer open infrastructure.

Cons: - Requires the Flatpak runtime to be installed. - Applications can be large due to bundled runtimes. - Desktop integration can sometimes feel slightly off compared to native packages.

How Users Feel About These

Community opinion on cross-distribution formats is mixed and often strong. Users of Arch-based distributions, in particular, tend to prefer native packages (from the AUR or official repositories) and may actively avoid AppImage, Snap, and Flatpak. Ubuntu users are generally comfortable with Snaps since they're built into the system, though even within the Ubuntu community there are detractors. Flatpak has been gaining broader acceptance, especially on Fedora and other non-Ubuntu distributions.

PyPI and `pip`

For Python applications specifically, distributing through PyPI (the Python Package Index) is another option. Users install your application with pip install yourapp. This is very natural for Python developers, and pip is available everywhere Python is installed.

However, this approach has limitations for GUI applications. Your users need to have Python installed at a compatible version, and managing system-level dependencies (like Qt libraries) through pip can be tricky. It works well when your audience is technical and already has a Python environment set up, but it's less ideal for distributing to general desktop users.

Tarball (`.tar.gz`)

A plain tarball containing your source code (or a bundled application created with a tool like PyInstaller) is the most minimal approach. It's universally compatible but puts the most burden on the user — they need to know how to extract it, handle dependencies, and run it.

This is fine for developer-oriented tools or as a fallback alongside more polished formats, but it's rarely the best primary distribution method for a GUI application.

So, What Should You Choose?

Here's a practical framework for deciding:

Audience	Recommended Format
Ubuntu / Mint users	`.deb`
Fedora / RHEL users	`.rpm`
Arch / Manjaro users	AUR `PKGBUILD` or PyPI
Broad Linux audience (one format)	AppImage or Flatpak
Python developers	PyPI (`pip install`)
Maximum reach	Offer multiple formats

If you can only pick one cross-distribution format, AppImage has the lowest barrier to entry for users (no runtime needed, just download and run) and Flatpak has the broadest community acceptance across non-Ubuntu distributions. If your audience is primarily Ubuntu-based, a .deb file is likely to be the most appreciated.

For many projects, offering a .deb for Debian/Ubuntu users alongside either an AppImage or Flatpak for everyone else is a solid strategy. If you have the time and your audience warrants it, adding an AUR package for Arch users and a PyPI listing for Python developers rounds things out well.

Practical Tools for Packaging Python GUI Apps

Whatever format you choose, you'll need tooling to create the packages. Here are some starting points:

.deb packages: Tools like dpkg-deb, stdeb, or fpm can help generate .deb files. The fpm tool is particularly helpful because it can generate both .deb and .rpm from a single description.
AppImage: python-appimage or appimage-builder can package Python applications into AppImages.
Flatpak: Flatpak uses manifest files to describe builds. The Flatpak documentation covers how to create manifests for Python applications.
Snap: Canonical provides snapcraft for building Snap packages, with support for Python applications.
PyPI: Use setuptools or flit to create a distributable Python package, then upload with twine.

Final Thoughts

There's no single "correct" answer to Linux packaging — the best format depends on who your users are and what they expect. The Linux desktop ecosystem is diverse by design, and that diversity extends to packaging. Start with the format that matches your primary audience, and expand from there as your user base grows. If you're unsure, asking your users directly (as in the forum discussion that inspired this article) is always a good move.

Python GUIs - deployment

Deploying PyQt6 Apps on macOS with py2app — How to package your PyQt6 application into a standalone macOS .app bundle

Why Does py2app Crash? The Anaconda Problem

Setting Up a Clean Virtual Environment

Preparing Your Application

Creating the setup.py File

Building the Application

Handling .ui Files at Runtime

An Alternative: Skip .ui Files Entirely

Troubleshooting Checklist

Complete Working Example

Linux Packaging Preferred Formats for Python GUI Applications — Choosing the right packaging format for distributing your Python apps on Linux

Distribution-Specific Packages: .deb and .rpm

Cross-Distribution Formats: AppImage, Snap, and Flatpak

AppImage

Snap

Flatpak

How Users Feel About These

PyPI and pip

Tarball (.tar.gz)

So, What Should You Choose?

Practical Tools for Packaging Python GUI Apps

Final Thoughts

Distribution-Specific Packages: `.deb` and `.rpm`

PyPI and `pip`

Tarball (`.tar.gz`)