Fehlerbild: Der Build auf Windows startet, ergibt aber keine macOS-App. Schnellster Weg: Bauen Sie mit PyInstaller 6.22.3 auf macOS, prüfen Sie zuerst den Verzeichnis-Modus und wechseln Sie erst nach einer vollständigen Abnahme zur Einzeldatei.
Das gilt, wenn Sie ein Python-Skript oder eine GUI-Anwendung für Macs bereitstellen möchten. Ein erfolgreicher Build ist noch kein Nachweis für reproduzierbare Forschungsergebnisse oder eine fertige öffentliche Verteilung.
Für Sie, wenn: Sie als Master- oder Promotionsstudierende Python-Auswertungen an Mac-nutzende Betreuende oder Kooperationspartner übergeben. Für Sie, wenn: Sie eine Forschungs-GUI mit Daten, Vorlagen oder nativen Abhängigkeiten paketieren. Für Sie, wenn: Sie in der Hochschul-IT einen wiederholbaren Build- und Abnahmeprozess für eine Arbeitsgruppe festlegen.
Vor dem Build: Zielplattform und Abnahmeziel festlegen
PyInstaller erzeugt eine Anwendung für das Betriebssystem, auf dem der Build läuft. Wenn Sie eine macOS-Anwendung benötigen, führen Sie den Build daher in einer macOS-Umgebung aus; ein auf Windows erzeugtes Paket wird nicht durch Umbenennen oder Kopieren zu einer Mac-App. Die PyInstaller-Dokumentation zu Betriebssystemen und Builds erläutert diese Plattformbindung. Prüfen Sie die Aussage auch in der Änderungshistorie der Version 6.22.3, bevor Sie eine Versionsnummer in Ihre Build-Aufzeichnung übernehmen.
Legen Sie außerdem fest, was „fertig“ in Ihrem Fall bedeutet. Ein Programm für den internen Test einer Arbeitsgruppe muss nicht denselben Verteilungsstatus haben wie eine Anwendung für externe Kooperationspartner. Eine öffentlich angebotene App braucht zusätzlich eine Prüfung der geltenden macOS-Signatur- und Verteilungsanforderungen.
Trennen Sie diese Ziele vor der Arbeit:
- Interne Abnahme: Die App startet auf dem vorgesehenen Mac, verarbeitet einen bekannten Beispieldatensatz und legt Ergebnisse am erwarteten Ort ab.
- Übergabe an Kooperationspartner: Zusätzlich müssen Installation, benötigte Ressourcen, Konfiguration und Fehlerprotokolle für Personen außerhalb Ihrer Entwicklungsumgebung verständlich sein.
- Öffentliche Verteilung: Neben dem Funktionstest prüfen Sie Signierung, Notarisierung und die aktuellen Verteilungsbedingungen anhand der offiziellen Übersicht zur macOS-Softwareverteilung.
Projektkopie und Belege vor dem ersten Build vorbereiten
Bauen Sie nicht direkt aus dem einzigen Arbeitsverzeichnis. Legen Sie eine getrennte, rücksetzbare Projektkopie an und halten Sie fest, welcher Quellstand in das Paket eingeht. So können Sie Build-Änderungen zurücknehmen, ohne Analyseskripte, Eingabedaten oder lokale Konfigurationen zu überschreiben.
Dokumentieren Sie in einer kurzen Build-Notiz:
- die installierte Python-Version und die PyInstaller-Version,
- die installierten Projektabhängigkeiten samt ihrer Herkunft,
- die Zielarchitektur des verwendeten Macs,
- den Build-Befehl und die gewählte Paketierungsart,
- den verwendeten Eingabedatensatz sowie den erwarteten Ergebnisort.
Erstellen Sie danach ein Inventar der nicht im Python-Code enthaltenen Bestandteile. Dazu gehören beispielsweise Konfigurationsdateien, Vorlagen, Wörterbücher, Referenzdateien, Icons oder andere Dateien, die zur Ausführung benötigt werden. Halten Sie für jede Datei fest, ob sie unveränderlicher Bestandteil der App oder veränderliche Nutzereingabe beziehungsweise Ausgabe ist. Diese Trennung bestimmt später, ob eine Datei in das Paket gehört und wo das Programm sie zur Laufzeit sucht.
Prüfen Sie vor dem Test auch den Datenrahmen: Verwenden Sie für den ersten Build einen nicht sensiblen Beispieldatensatz. Vergewissern Sie sich, dass keine personenbezogenen Daten, vertraulichen Forschungsdaten oder Zugangsdaten unbeabsichtigt in die Projektkopie, Build-Ausgabe oder Protokolle gelangen. Bei einer externen Build-Umgebung müssen Sie vorab klären, ob die Verarbeitung Ihrer Daten nach den Vorgaben Ihrer Einrichtung und der DSGVO zulässig ist.
Ersten macOS-Build im Verzeichnis-Modus erstellen
Beginnen Sie mit einer sauberen Projektumgebung, in der nur die für Ihre Anwendung benötigten Abhängigkeiten installiert sind. Installieren und starten Sie PyInstaller gemäß der offiziellen Nutzungsdokumentation. Verwenden Sie für den ersten Durchlauf den Verzeichnis-Modus: Er macht die erzeugten Dateien sichtbar und erleichtert die Suche nach fehlenden Modulen, Bibliotheken oder Ressourcen.
Der Befehl kann grundsätzlich dieser Form folgen:
pyinstaller --onedir --name ForschungsApp main.pyErsetzen Sie ForschungsApp und main.py durch die Namen Ihres Projekts. Ergänzen Sie nicht wahllos Optionen, nur weil sie in einem Beispiel vorkommen: Notieren Sie jede Änderung am Build-Befehl, damit Sie bei einem Fehler nachvollziehen können, was sich geändert hat. Die offizielle Dokumentation beschreibt die Optionen und das Verhalten der Modi; die konkreten Anforderungen hängen von Ihrer Anwendung ab.
Prüfen Sie anschließend den Inhalt des erzeugten Verzeichnisses. Starten Sie das Programm nicht nur aus der Entwicklungsumgebung, sondern testen Sie die gebaute Anwendung selbst. Achten Sie darauf, ob importierte Module, dynamische Bibliotheken und benötigte Daten vorhanden sind. Die PyInstaller-Unterlagen zu Spec-Dateien erläutern, wie zusätzliche Daten und Binärdateien im Build beschrieben werden. Für Abhängigkeiten, die spezielle Behandlung benötigen, beschreibt die Dokumentation zum Hook-Mechanismus die vorgesehene Erweiterungsmöglichkeit.
Was prüfen Sie, wenn die App eine Forschungsdatei nicht findet?
Unterscheiden Sie zuerst zwischen einer Datei, die zur App gehört, und einer Datei, die Sie oder die Nutzer zur Laufzeit auswählen. Eine mitgelieferte Vorlage kann in den Build aufgenommen werden. Ein Messdatensatz, den ein Nutzer auswählt, sollte dagegen nicht als unveränderliche App-Ressource behandelt werden.
Gehen Sie bei einem fehlenden Pfad systematisch vor:
- Starten Sie die App aus dem Finder und prüfen Sie, ob das Verhalten vom Start im Terminal abweicht.
- Protokollieren Sie den tatsächlich verwendeten Dateipfad, statt nur den Dateinamen auszugeben.
- Prüfen Sie, ob der Pfad aus dem aktuellen Arbeitsverzeichnis abgeleitet wird. Dieses ist beim Finder-Start nicht zuverlässig dasselbe wie das Projektverzeichnis.
- Ordnen Sie die Datei als Paketressource, Nutzereingabe, Konfiguration oder Ausgabe ein.
- Ergänzen Sie nur die tatsächlich benötigten Paketressourcen und bauen Sie erneut.
- Wiederholen Sie den Test mit einer frischen Projektkopie und dem unveränderten Beispieldatensatz.
Wenn Sie nach einer Änderung weiterhin einen Fehler sehen, sichern Sie die genaue Fehlermeldung, den Startweg und die verwendete Eingabe. Ein reproduzierbarer Fehlerbericht ist hilfreicher als die pauschale Aussage „PyInstaller hat die Datei nicht mitgenommen“.
GUI, Pfade und Analyseergebnisse nach dem Build abnehmen
Ein erfolgreicher Start bestätigt nur einen Teil der Funktion. Führen Sie die Abnahme auf dem gebauten Programm aus und nehmen Sie dabei denselben repräsentativen Beispieldatensatz, den Sie für den Vergleich mit dem ursprünglichen Python-Projekt verwenden.
Prüfen Sie nacheinander:
- Start aus dem Finder: Öffnet sich das Fenster, und bleibt es nach der ersten Interaktion verfügbar?
- Bedienung: Funktionieren Menüs, Schaltflächen, Datei-Dialoge und Fehlermeldungen wie vorgesehen?
- Dateieingabe: Kann die Anwendung eine ausgewählte Datei lesen, auch wenn sie nicht im Projektverzeichnis liegt?
- Ausgabe: Wird das Ergebnis an dem angezeigten beziehungsweise dokumentierten Ort gespeichert?
- Vergleich: Stimmen die fachlich relevanten Ausgaben mit dem Ergebnis des ursprünglichen Python-Projekts überein?
- Protokollierung: Können Sie erkennen, ob ein Fehler beim Laden, bei der Oberfläche, beim Schreiben oder in der Analyse entsteht?
Für eine unabhängige Prüfung verwenden Sie eine zweite Projektkopie oder ein anderes vorgesehenes Mac-Benutzerkonto. Installieren Sie dort nicht nachträglich fehlende Entwicklungsabhängigkeiten, bevor Sie den ersten Test durchgeführt haben. Andernfalls testen Sie nicht das Paket, sondern unbemerkt wieder Ihre Entwicklungsumgebung.
Welche Build-Variante passt zu Ihrem Übergabeweg?
Die Modi sind keine Rangliste von „schlechter“ zu „besser“. Der Verzeichnis-Modus bietet beim ersten Build bessere Prüfbarkeit; eine Einzeldatei kann die Übergabe vereinfachen, verlangt aber eine erneute Prüfung des tatsächlichen Laufzeitverhaltens. PyInstaller dokumentiert --onedir und --onefile in seiner Übersicht zu den Betriebsmodi.
| Kriterium | Verzeichnis-Modus (--onedir) | Einzeldatei-Modus (--onefile) |
|---|---|---|
| Fehlersuche | Dateien und Verzeichnisstruktur lassen sich gezielt untersuchen. | Fehlende Inhalte sind im Paket weniger unmittelbar sichtbar. |
| Übergabe | Sie müssen das erzeugte App-Verzeichnis als Einheit behandeln. | Die Übergabe kann kompakter wirken, ersetzt aber keine Abnahme. |
| Ressourcen | Sie können prüfen, welche Ressourcen im Build-Verzeichnis liegen. | Sie müssen zusätzlich testen, wie die Anwendung mit eingebetteten Ressourcen umgeht. |
| Geeigneter Zeitpunkt | Erster Build und Abnahme der Abhängigkeiten. | Erst nach erfolgreicher Prüfung des Verzeichnis-Builds. |
| Bewertung für den Start | Hoch: gute Transparenz während der Fehlersuche. | Mittel: mögliche Vereinfachung bei der Übergabe, aber mehr Prüfbedarf. |
- Wenn Sie noch fehlende Module, Bibliotheken oder Vorlagen suchen, dann bleiben Sie im Verzeichnis-Modus.
- Wenn die Anwendung geprüft ist und eine einfachere Übergabe einen konkreten Nutzen bringt, dann testen Sie den Einzeldatei-Modus separat.
- Wenn die App veränderliche Nutzerdaten oder Ausgaben verwaltet, dann halten Sie diese außerhalb des unveränderlichen Ressourcenbereichs.
- Wenn Sie den Modus wechseln, dann wiederholen Sie Start-, Eingabe-, Ergebnis- und Finder-Tests mit derselben Vergleichsgrundlage.
- Wenn externe Nutzer die App installieren sollen, dann behandeln Sie Signatur und Verteilung als eigene Abnahmephase statt als Nebenwirkung des Builds.
| Abnahmestufe | Was ist belegt? | Was ist noch offen? | Bewertung |
|---|---|---|---|
| App startet | Das Paket lässt sich auf der geprüften Umgebung öffnen. | Ressourcen, Datenverarbeitung und Ergebnisse können weiterhin fehlerhaft sein. | Unvollständig |
| Analyse reproduziert sich | Der repräsentative Test liefert die vereinbarten fachlichen Ergebnisse. | Installation und externe Verteilung sind noch nicht automatisch geprüft. | Für interne Forschungsabnahme geeignet |
| App ist für externe Verteilung vorbereitet | Funktion, Ressourcen und Verteilungsbedingungen wurden geprüft. | Die Anforderungen können sich ändern und müssen aktuell abgeglichen werden. | Nur nach dokumentierter Verteilungsprüfung |
Verteilung und Übergabe getrennt vom Funktionstest behandeln
Benötigt eine PyInstaller-App Signierung und Notarisierung?
Das hängt davon ab, wie und an wen Sie die App verteilen. Für einen internen Funktionstest beantworten Sie zunächst die technische Frage, ob die Anwendung korrekt startet und die vereinbarten Forschungsaufgaben ausführt. Bei einer externen Übergabe oder öffentlichen Verteilung müssen Sie zusätzlich die jeweils geltenden macOS-Anforderungen prüfen. Die offizielle Übersicht zur Verteilung von macOS-Software ist dafür maßgeblich; leiten Sie aus einem erfolgreichen PyInstaller-Build keine Aussage über Signatur oder Notarisierung ab.
Umgehen Sie keine Sicherheitsprüfung, um einen Test scheinbar zu „reparieren“. Dokumentieren Sie stattdessen, für welchen Verteilungsweg die Anwendung gedacht ist, und gleichen Sie die dafür vorgesehenen Schritte mit der aktuellen offiziellen Dokumentation ab. Wenn Ihre Hochschule eine interne Verteilung oder ein zentrales Installationsverfahren nutzt, beziehen Sie die zuständige IT-Stelle ein, bevor Sie eine App an Kooperationspartner weitergeben.
Für die Übergabe gehören mindestens folgende Angaben in die Begleitunterlagen: Zweck der Anwendung, geprüfte Eingabe, erwartete Ausgabe, Ablageort für Ergebnisse, benötigte Konfiguration und Kontaktweg für reproduzierbare Fehlermeldungen. Bei Forschungssoftware sollten Sie außerdem festhalten, welcher Quellstand und welche Abhängigkeitsgrundlage dem Paket zugrunde liegen. So können andere Forschende unterscheiden, ob sie die Analyse reproduzieren oder lediglich eine bereits erzeugte App starten.
Wer keinen lokalen Mac für den Build oder die Abnahme zur Verfügung hat, kann zunächst prüfen, ob eine gemietete macOS-Umgebung in den eigenen Arbeitsablauf passt. Die Informationen zu einem Remote-Mac von MACGPU helfen Ihnen, Zugang und Nutzung vorab einzuordnen. Klären Sie vor dem Übertragen von Projektdateien, welche Daten für den Build erforderlich sind und ob diese Daten überhaupt in eine externe Umgebung gelangen dürfen.
Mit einem dokumentierten Ergebnis abschließen
Schließen Sie den Vorgang erst ab, wenn Sie getrennt festhalten können, ob die App startet, ob die Forschungsanalyse mit der vorgesehenen Eingabe reproduzierbar ist und ob der gewählte Verteilungsweg geprüft wurde. Ein Build-Protokoll sollte den Quellstand, die Umgebung, den Befehl, Ressourcenänderungen, Testeingaben und beobachtete Ergebnisse enthalten. So kann eine andere Person den Vorgang nachvollziehen, statt sich auf eine einmalige Erfolgsmeldung zu verlassen.
Wenn Ihr aktueller Rechner oder Laborserver nur Windows oder Linux bereitstellt, entstehen bei einem ausschließlich dort durchgeführten Build zwei konkrete Nachteile: Das Ergebnis ist nicht die gewünschte macOS-Anwendung, und Sie können das Verhalten unter macOS nicht direkt abnehmen. Für einzelne Builds oder gezielte Kompatibilitätstests kann ein zeitlich begrenzter Remote-Mac diese Lücke schließen; Sie erhalten dabei eine reale macOS-Umgebung, ohne sofort ein eigenes Gerät anschaffen zu müssen. Falls Ihre Arbeitsgruppe dagegen dauerhaft umfangreiche Builds ausführt oder physische Schnittstellen benötigt, ist ein eigener Mac möglicherweise die passendere Lösung. Vergleichen Sie dafür auch die Informationen zu einem Mac von MACGPU mit Ihrem tatsächlichen, wiederkehrenden Bedarf.
Für PyInstaller 6.22.3 auf dem Mac bleibt die sichere Reihenfolge: auf macOS bauen, zuerst den Verzeichnis-Modus prüfen, Ergebnisse mit dem ursprünglichen Projekt vergleichen und erst danach über Einzeldatei und externe Verteilung entscheiden.