Python / Code kompilieren und EXE-Dateien erstellen

Um Python-Code als Windows-EXE weiterzugeben, kann PyInstaller Programm, Python-Laufzeit und benötigte Bibliotheken bündeln. Eine mit py_compile erzeugte .pyc enthält Python-Bytecode und ist keine eigenständige Windows-EXE. Prüfen Sie zuerst einen Ordner-Build und wechseln Sie bei Bedarf zur Einzeldatei, damit sich Fehler leichter eingrenzen lassen.

Bytecode kompilieren oder eine EXE bündeln

py_compile wandelt Quellcode in Bytecode-Dateien um. PyInstaller sammelt Interpreter und Abhängigkeiten zu einer verteilbaren Anwendung. Das ist etwas anderes als die Übersetzung eines gewöhnlichen Python-Programms über C in optimierten nativen Maschinencode. Ein Bundle beschleunigt die Ausführung nicht automatisch und verbirgt den Quellinhalt nicht sicher.

Das Ergebnis hängt von Betriebssystem und Architektur ab. Erstellen Sie Windows-EXEs unter Windows; PyInstaller ist kein Cross-Compiler, der sie unter Linux durch eine einzelne Option erzeugt. Prüfen Sie die unterstützten Umgebungen und die Kompatibilität Ihrer Pakete.

Arbeitsordner und virtuelle Umgebung vorbereiten

Verwenden Sie PowerShell unter Windows mit installiertem Python 3 und pip. Öffnen Sie ein Terminal in einem neuen Arbeitsordner und führen Sie diese Befehle nacheinander aus. Falls py -3 nicht verfügbar ist, ersetzen Sie es in der ersten Zeile durch den Pfad des installierten Python-Interpreters oder einen darauf verweisenden python-Befehl.

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install "pyinstaller==6.22.3"
.\.venv\Scripts\python.exe -m PyInstaller --version

.venv ist die virtuelle Umgebung dieses Projekts. Die weiteren Befehle rufen deren Python direkt auf; Aktivierungsskripte und Änderungen der PowerShell-Ausführungsrichtlinie sind daher unnötig. PyInstaller 6.22.3 legt die Beispielversion fest. Bei einer anderen Version prüfen Sie Kompatibilität und Optionen erneut. Die Installation muss erfolgreich sein und der letzte Befehl 6.22.3 ausgeben.

Installieren Sie zusätzliche Anwendungsabhängigkeiten in dieselbe Umgebung. Ein globales Python mit vielen unbenutzten Paketen kann die Analyse und Verwaltung des Ergebnisses erschweren.

Vollständiges Beispiel speichern und Bytecode erzeugen

Erstellen Sie im Arbeitsordner die UTF-8-Datei hello.py:

print("Hello, packaging!")

Hello, packaging!

Führen Sie zuerst den Quellcode aus. Er muss die oben gezeigte Meldung ausgeben.

.\.venv\Scripts\python.exe hello.py

Für eine reine Bytecode-Kompilierung verwenden Sie:

.\.venv\Scripts\python.exe -m py_compile hello.py

Bei Erfolg entsteht normalerweise ohne Ausgabe eine Datei wie hello.cpython-312.pyc in __pycache__. Die Versionskennung hängt von Python ab. Umbenennen in EXE macht sie nicht eigenständig; Bytecode benötigt weiterhin eine kompatible Python-Laufzeit.

Einen Ordner-Build erstellen und verteilen

Führen Sie im Arbeitsordner beide Befehle aus, den zweiten erst nach erfolgreichem Build.

.\.venv\Scripts\python.exe -m PyInstaller --onedir --name hello-folder hello.py
.\dist\hello-folder\hello-folder.exe

Die Ausgabe lautet Hello, packaging!. Verteilen Sie den gesamten Ordner dist\hello-folder mit EXE und unterstützenden Dateien. Bei alleiniger Weitergabe der EXE können Bibliotheken fehlen. Hilfsdateien können unter _internal liegen; die genaue Struktur hängt von Paketen und Optionen ab.

build enthält Zwischen- und Diagnosedateien, hello-folder.spec die Build-Konfiguration. Empfänger erhalten das Ergebnis unter dist, nicht Ihre Ordner build oder .venv. Weitere Optionen erläutert die PyInstaller-Befehlsreferenz.

Eine einzelne EXE erzeugen

Funktioniert der Ordner-Build, bündeln Sie denselben Quellcode als Einzeldatei. Der andere Name hält beide Ergebnisse für einen Vergleich verfügbar.

.\.venv\Scripts\python.exe -m PyInstaller --onefile --name hello-single hello.py
.\dist\hello-single.exe

dist\hello-single.exe lässt sich als einzelne Datei weitergeben und erzeugt dieselbe Ausgabe. Beim Start werden interne Dateien temporär entpackt, was den Start verlangsamen kann. Beurteilen Sie Größe und Geschwindigkeit an Ihrer tatsächlichen Anwendung, statt feste Vorteile anzunehmen.

Fügen Sie diesem Konsolenbeispiel kein --windowed hinzu. Für GUI-Programme ohne Konsole kann die Option passen; bei Programmen mit print() oder input() erschwert sie Ein-/Ausgabe und Fehlerdiagnose. Administratorausführung oder das Abschalten von Sicherheitssoftware sind keine pauschalen Ersatzlösungen für die Ursachenanalyse.

Ordner- und Einzeldatei-Beispiel wurden unter Windows mit Python 3.12.14 und PyInstaller 6.22.3 erstellt und anhand ihrer Ausgabe geprüft. Die Prüfung betrifft Konsolenbeispiele auf demselben Host, keinen separaten PC ohne Python und keine GUI-Anwendung.

Text, Bilder und weitere Datendateien einbinden

Nehmen Sie nicht an, dass alle gelesenen Dateien automatisch gesammelt werden. Speichern Sie message.txt in UTF-8 mit der einzelnen Zeile Hello from bundled data!. Erstellen Sie daneben hello_data.py mit diesem vollständigen Inhalt:

from pathlib import Path

message = Path(__file__).resolve().with_name("message.txt")
print(message.read_text(encoding="utf-8").strip())

Hello from bundled data!

Quellcode und folgender Bundle-Aufruf müssen dieselbe Meldung ausgeben. Ein Pfad relativ zu __file__ hängt nicht vom aktuellen Terminalordner ab und kann Dateien innerhalb des Bundles finden.

.\.venv\Scripts\python.exe -m PyInstaller --onefile --name hello-data --add-data "message.txt:." hello_data.py
.\dist\hello-data.exe

--add-data "message.txt:." legt die Datei auf der obersten Bundle-Ebene ab. Die aktuelle Dokumentation verwendet einen Doppelpunkt als Trennzeichen; vermischen Sie dies nicht mit älteren plattformspezifischen Beispielen. Stimmen Sie Pfade für Bilder und Einstellungen mit den Regeln zum Einbinden von Daten ab. Änderungen an aus einer Einzeldatei entpackten Daten sind kein dauerhafter Speicher. Speichern Sie Benutzereinstellungen und Ergebnisse an einem getrennten beschreibbaren Benutzerort.

Fehler suchen und die Weitergabe prüfen

1. Schließt die EXE sofort, starten Sie sie in PowerShell statt per Doppelklick, um den Fehler zu lesen. Prüfen Sie vorher den Quellcode in derselben virtuellen Umgebung.
2. Bei fehlenden Modulen kontrollieren Sie Installation und Importmethode. Dynamische Imports können zusätzliche Sammeloptionen erfordern. Lesen Sie build\Name\warn-Name.txt; nicht jede Warnung ist fatal.
3. Bei fehlenden Daten vergleichen Sie das Ziel von --add-data mit dem Codepfad. Wechseln Sie zum Ordner-Build zurück, um Dateien und Ausführungspfade zu untersuchen.
4. Testen Sie die Funktionen unter Zielbetriebssystem und Zielarchitektur. Dazu gehören eine separate Umgebung ohne Python, Dateizugriffe, externe Programme und die Weitergabebedingungen der enthaltenen Pakete.

Die PyInstaller-Fehlerhilfe erläutert Diagnosemethoden. Unterscheiden Sie Build und Ausführung und halten Sie reproduzierbaren Quellcode, Paketversionen und Fehlermeldungen für die Ursachenanalyse fest.