1. Befehlszeile und Umgebung

Der CPython-Interpreter durchsucht die Befehlszeile und die Umgebung nach verschiedenen Einstellungen.

Die Befehlszeilen-Schemata anderer Umsetzungen können davon abweichen. Weitere Quellen stehen unter Alternative Implementierungen.

1.1. Befehlszeile

Beim Aufruf von Python kannst du jede dieser Optionen angeben:

python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]

Der häufigste Fall ist natürlich der einfache Aufruf eines Skripts:

python myscript.py

1.1.1. Optionen der Schnittstelle

Die Schnittstelle des Interpreters ähnelt der der UNIX-Shell, bietet aber einige zusätzliche Aufrufarten:

  • Wird er mit der Standardeingabe an einem tty-Gerät aufgerufen, fragt er nach Befehlen und führt sie aus, bis ein EOF gelesen wird (ein Dateiende-Zeichen, das du unter UNIX mit Ctrl-D und unter Windows mit Ctrl-Z, Enter erzeugst). Mehr zum interaktiven Modus unter Interaktiver Modus.

  • Wird er mit einem Dateinamen als Argument oder mit einer Datei als Standardeingabe aufgerufen, liest und führt er ein Skript aus dieser Datei aus.

  • Wird er mit einem Verzeichnisnamen als Argument aufgerufen, liest und führt er ein passend benanntes Skript aus diesem Verzeichnis aus.

  • Wird er mit -c command aufgerufen, führt er die als command angegebenen Python-Anweisungen aus. command darf dabei mehrere, durch Zeilenumbrüche getrennte Anweisungen enthalten. Führende Leerzeichen sind in Python-Anweisungen bedeutsam!

  • Wird er mit -m module-name aufgerufen, wird das angegebene Modul über den üblichen Importmechanismus gesucht und als Skript ausgeführt.

Im nicht interaktiven Modus wird die ganze Eingabe geparst, bevor sie ausgeführt wird.

Eine Schnittstellenoption beendet die Liste der Optionen, die der Interpreter verbraucht. Alle folgenden Argumente landen in sys.argv — beachte, dass das erste Element, der Index null (sys.argv[0]), eine Zeichenkette ist, die die Herkunft des Programms widerspiegelt.

-c <command>

Führt den Python-Code in command aus. command kann eine oder mehrere durch Zeilenumbrüche getrennte Anweisungen sein, wobei führende Leerzeichen wie in gewöhnlichem Modulcode bedeutsam sind.

Ist diese Option angegeben, ist das erste Element von sys.argv gleich "-c", und das aktuelle Verzeichnis wird an den Anfang von sys.path gestellt (sodass Module aus diesem Verzeichnis als Module der obersten Ebene importiert werden können).

Löst ein Auditing-Ereignis cpython.run_command mit dem Argument command aus.

-m <module-name>

Sucht das Modul über den üblichen Importmechanismus und führt seinen Inhalt als Modul __main__ aus.

Da das Argument der Name eines Moduls ist, darfst du keine Dateiendung angeben (.py). Der Modulname sollte ein gültiger absoluter Python-Modulname sein, die Umsetzung erzwingt das aber nicht immer (sie erlaubt dir zum Beispiel möglicherweise einen Namen mit Bindestrich).

Paketnamen (einschließlich Namespace-Pakete) sind ebenfalls erlaubt. Wird anstelle eines gewöhnlichen Moduls ein Paketname angegeben, führt der Interpreter <pkg>.__main__ als Hauptmodul aus. Dieses Verhalten ist absichtlich dem Umgang mit Verzeichnissen und ZIP-Dateien nachempfunden, die dem Interpreter als Skriptargument übergeben werden.

Bemerkung

Diese Option lässt sich nicht mit integrierten Modulen und mit in C geschriebenen Erweiterungsmodulen verwenden, weil diese keine Python-Moduldateien haben. Für vorkompilierte Module lässt sie sich dagegen verwenden, auch wenn die ursprüngliche Quelldatei nicht vorliegt.

Ist diese Option angegeben, ist das erste Element von sys.argv der vollständige Pfad zur Moduldatei (während die Moduldatei gesucht wird, ist das erste Element auf "-m" gesetzt). Wie bei der Option -c wird das aktuelle Verzeichnis an den Anfang von sys.path gestellt.

Mit der Option -I lässt sich das Skript im abgeschotteten Modus ausführen, in dem sys.path weder das aktuelle Verzeichnis noch das site-packages-Verzeichnis des Benutzers enthält. Alle Umgebungsvariablen PYTHON* werden dabei ebenfalls ignoriert.

Viele Module der Standardbibliothek enthalten Code, der bei ihrer Ausführung als Skript aufgerufen wird. Ein Beispiel ist das Modul timeit:

python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details

Löst ein Auditing-Ereignis cpython.run_module mit dem Argument module-name aus.

Siehe auch

runpy.run_module()

Gleichwertige Funktionalität, die Python-Code direkt zur Verfügung steht

PEP 338 – Executing modules as scripts

Geändert in Version 3.1: Gib den Paketnamen an, um ein Untermodul __main__ auszuführen.

Geändert in Version 3.4: Namespace-Pakete werden ebenfalls unterstützt

-

Liest Befehle von der Standardeingabe (sys.stdin). Ist die Standardeingabe ein Terminal, gilt -i implizit.

Ist diese Option angegeben, ist das erste Element von sys.argv gleich "-", und das aktuelle Verzeichnis wird an den Anfang von sys.path gestellt.

Löst ein Auditing-Ereignis cpython.run_stdin ohne Argumente aus.

<script>

Führt den Python-Code in script aus. script muss ein Pfad im Dateisystem sein (absolut oder relativ), der entweder auf eine Python-Datei, auf ein Verzeichnis mit einer Datei __main__.py oder auf eine ZIP-Datei mit einer Datei __main__.py verweist.

Ist diese Option angegeben, ist das erste Element von sys.argv der Skriptname, wie er auf der Befehlszeile angegeben wurde.

Verweist der Skriptname direkt auf eine Python-Datei, wird das Verzeichnis dieser Datei an den Anfang von sys.path gestellt und die Datei als Modul __main__ ausgeführt.

Verweist der Skriptname auf ein Verzeichnis oder eine ZIP-Datei, wird der Skriptname an den Anfang von sys.path gestellt und die Datei __main__.py an diesem Ort als Modul __main__ ausgeführt.

Mit der Option -I lässt sich das Skript im abgeschotteten Modus ausführen, in dem sys.path weder das Verzeichnis des Skripts noch das site-packages-Verzeichnis des Benutzers enthält. Alle Umgebungsvariablen PYTHON* werden dabei ebenfalls ignoriert.

Löst ein Auditing-Ereignis cpython.run_file mit dem Argument filename aus.

Siehe auch

runpy.run_path()

Gleichwertige Funktionalität, die Python-Code direkt zur Verfügung steht

Ist keine Schnittstellenoption angegeben, gilt -i implizit, sys.argv[0] ist eine leere Zeichenkette (""), und das aktuelle Verzeichnis wird an den Anfang von sys.path gestellt. Außerdem sind Tabulator-Vervollständigung und das Bearbeiten der Eingabehistorie automatisch eingeschaltet, sofern auf deiner Plattform verfügbar (siehe Readline configuration).

Siehe auch

Aufrufen des Interpreters

Geändert in Version 3.4: Automatisches Einschalten von Tabulator-Vervollständigung und Historienbearbeitung.

1.1.2. Allgemeine Optionen

-?
-h
--help

Gibt eine kurze Beschreibung aller Befehlszeilenoptionen und der zugehörigen Umgebungsvariablen aus und beendet sich.

--help-env

Gibt eine kurze Beschreibung der Python-spezifischen Umgebungsvariablen aus und beendet sich.

Added in version 3.11.

--help-xoptions

Gibt eine Beschreibung der umsetzungsspezifischen -X-Optionen aus und beendet sich.

Added in version 3.11.

--help-all

Gibt die vollständigen Verwendungshinweise aus und beendet sich.

Added in version 3.11.

-V
--version

Gibt die Python-Versionsnummer aus und beendet sich. Eine Ausgabe könnte so aussehen:

Python 3.8.0b2+

Zweimal angegeben, gibt sie mehr über den Build aus, etwa:

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

Added in version 3.6: Die Option -VV.

1.1.3. Verschiedene Optionen

-b

Gibt eine Warnung aus, wenn bytes oder bytearray ohne Angabe einer Kodierung in str umgewandelt wird oder wenn bytes beziehungsweise bytearray mit str oder bytes mit int verglichen wird. Gibt einen Fehler aus, wenn die Option zweimal angegeben wird (-bb).

Geändert in Version 3.5: Betrifft auch Vergleiche von bytes mit int.

-B

Ist sie angegeben, versucht Python nicht, beim Import von Quellmodulen .pyc-Dateien zu schreiben. Siehe auch PYTHONDONTWRITEBYTECODE.

--check-hash-based-pycs default|always|never

Steuert das Prüfverhalten für hashbasierte .pyc-Dateien. Siehe Ungültigmachung von zwischengespeichertem Bytecode. Bei default werden geprüfte und ungeprüfte hashbasierte Bytecode-Cache-Dateien nach ihrer jeweiligen Standardbedeutung validiert. Bei always werden alle hashbasierten .pyc-Dateien gegen ihre zugehörige Quelldatei validiert, gleich ob geprüft oder ungeprüft. Bei never werden hashbasierte .pyc-Dateien nicht gegen ihre zugehörigen Quelldateien validiert.

Die Bedeutung zeitstempelbasierter .pyc-Dateien bleibt von dieser Option unberührt.

-d

Schaltet die Debug-Ausgabe des Parsers ein (nur für Fachleute). Siehe auch die Umgebungsvariable PYTHONDEBUG.

Diese Option setzt einen Debug-Build von Python voraus, andernfalls wird sie ignoriert.

-E

Ignoriert alle gesetzten Umgebungsvariablen PYTHON*, etwa PYTHONPATH und PYTHONHOME.

Siehe auch die Optionen -P und -I (abgeschottet).

-i

Wechselt nach der Ausführung in den interaktiven Modus.

Mit der Option -i wird in jedem der folgenden Fälle in den interaktiven Modus gewechselt:

  • Wenn ein Skript als erstes Argument übergeben wird

  • Wenn die Option -c verwendet wird

  • Wenn die Option -m verwendet wird

Der interaktive Modus startet auch dann, wenn sys.stdin kein Terminal zu sein scheint. Die Datei PYTHONSTARTUP wird nicht gelesen.

Das kann nützlich sein, um globale Variablen oder einen Stack-Trace zu untersuchen, wenn ein Skript eine Ausnahme auslöst. Siehe auch PYTHONINSPECT.

-I

Führt Python im abgeschotteten Modus aus. Das zieht auch die Optionen -E, -P und -s nach sich.

Im abgeschotteten Modus enthält sys.path weder das Verzeichnis des Skripts noch das site-packages-Verzeichnis des Benutzers. Alle Umgebungsvariablen PYTHON* werden ebenfalls ignoriert. Weitere Einschränkungen können hinzukommen, um das Einschleusen von Schadcode durch den Benutzer zu verhindern.

Added in version 3.4.

-O

Entfernt assert-Anweisungen und jeden Code, der vom Wert von __debug__ abhängt. Ergänzt den Dateinamen kompilierter Dateien (Bytecode) um .opt-1 vor der Endung .pyc (siehe PEP 488). Siehe auch PYTHONOPTIMIZE.

Geändert in Version 3.5: Die .pyc-Dateinamen werden gemäß PEP 488 geändert.

-OO

Wirkt wie -O und verwirft zusätzlich Docstrings. Ergänzt den Dateinamen kompilierter Dateien (Bytecode) um .opt-2 vor der Endung .pyc (siehe PEP 488).

Geändert in Version 3.5: Die .pyc-Dateinamen werden gemäß PEP 488 geändert.

-P

Stellt keinen möglicherweise unsicheren Pfad an den Anfang von sys.path:

  • Befehlszeile python -m module: Das aktuelle Arbeitsverzeichnis wird nicht vorangestellt.

  • Befehlszeile python script.py: Das Verzeichnis des Skripts wird nicht vorangestellt. Ist es eine symbolische Verknüpfung, werden symbolische Verknüpfungen aufgelöst.

  • Befehlszeilen python -c code und python (REPL): Es wird keine leere Zeichenkette vorangestellt, die für das aktuelle Arbeitsverzeichnis steht.

Siehe auch die Umgebungsvariable PYTHONSAFEPATH sowie die Optionen -E und -I (abgeschottet).

Added in version 3.11.

-q

Zeigt die Copyright- und Versionsmeldungen auch im interaktiven Modus nicht an.

Added in version 3.2.

-R

Schaltet die Hash-Randomisierung ein. Diese Option wirkt nur, wenn die Umgebungsvariable PYTHONHASHSEED auf etwas anderes als random gesetzt ist, denn die Hash-Randomisierung ist standardmäßig eingeschaltet.

In früheren Python-Versionen schaltet diese Option die Hash-Randomisierung ein, sodass die __hash__()-Werte von str- und bytes-Objekten mit einem unvorhersehbaren Zufallswert „gesalzen“ werden. Innerhalb eines einzelnen Python-Prozesses bleiben sie zwar konstant, über wiederholte Python-Aufrufe hinweg sind sie jedoch nicht vorhersehbar.

Die Hash-Randomisierung soll vor einem Denial-of-Service schützen, der durch sorgfältig gewählte Eingaben entsteht, die das Verhalten im schlechtesten Fall beim Aufbau eines dict ausnutzen – eine Komplexität von O(n2). Einzelheiten unter https://ocert.org/advisories/ocert-2011-003.html.

Mit PYTHONHASHSEED kannst du einen festen Wert für das Hash-Seed-Geheimnis setzen.

Added in version 3.2.3.

Geändert in Version 3.7: Die Option wird nicht mehr ignoriert.

-s

Fügt das site-packages-Verzeichnis des Benutzers nicht zu sys.path hinzu.

Siehe auch PYTHONNOUSERSITE.

Siehe auch

PEP 370 – site-packages-Verzeichnis pro Benutzer

-S

Schaltet den Import des Moduls site und die damit verbundenen site-abhängigen Änderungen an sys.path ab. Diese Änderungen bleiben auch dann abgeschaltet, wenn site später ausdrücklich importiert wird (rufe site.main() auf, wenn du sie auslösen willst).

-u

Erzwingt, dass die Ströme stdout und stderr ungepuffert sind. Auf den Strom stdin hat diese Option keine Wirkung.

Siehe auch PYTHONUNBUFFERED.

Geändert in Version 3.7: Die Textschicht der Ströme stdout und stderr ist jetzt ungepuffert.

-v

Gibt bei jeder Initialisierung eines Moduls eine Meldung aus, die den Ort nennt (Dateiname oder integriertes Modul), von dem es geladen wird. Zweimal angegeben (-vv), gibt sie für jede Datei eine Meldung aus, die bei der Suche nach einem Modul geprüft wird. Außerdem liefert sie Informationen zum Aufräumen der Module beim Beenden.

Geändert in Version 3.10: Das Modul site meldet die site-spezifischen Pfade und die verarbeiteten .pth-Dateien.

Siehe auch PYTHONVERBOSE.

-W arg

Steuerung der Warnungen. Die Warnmaschinerie von Python gibt Warnmeldungen standardmäßig auf sys.stderr aus.

Die einfachsten Einstellungen wenden eine bestimmte Aktion bedingungslos auf alle Warnungen an, die ein Prozess ausgibt (auch auf die, die sonst standardmäßig ignoriert werden):

-Wdefault  # Einmal pro Aufrufstelle warnen
-Werror    # In Ausnahmen umwandeln
-Walways   # Jedes Mal warnen
-Wall      # Dasselbe wie -Walways
-Wmodule   # Einmal pro aufrufendem Modul warnen
-Wonce     # Einmal pro Python-Prozess warnen
-Wignore   # Niemals warnen

Die Aktionsnamen lassen sich beliebig abkürzen, der Interpreter löst sie zum passenden Aktionsnamen auf. So ist -Wi dasselbe wie -Wignore.

Die vollständige Form des Arguments lautet:

action:message:category:module:lineno

Leere Felder passen auf alle Werte, nachgestellte leere Felder dürfen weggelassen werden. So ignoriert -W ignore::DeprecationWarning alle DeprecationWarning-Warnungen.

Das Feld action wirkt wie oben beschrieben, gilt aber nur für Warnungen, die auf die übrigen Felder passen.

Das Feld message muss auf die gesamte Warnmeldung passen, wobei Groß- und Kleinschreibung keine Rolle spielt.

Das Feld category passt auf die Warnkategorie (z. B. DeprecationWarning). Dabei muss es sich um einen Klassennamen handeln. Geprüft wird, ob die tatsächliche Warnkategorie der Meldung eine Unterklasse der angegebenen Warnkategorie ist.

Das Feld module passt auf den (vollständig qualifizierten) Modulnamen, wobei Groß- und Kleinschreibung hier eine Rolle spielt.

Das Feld lineno passt auf die Zeilennummer, wobei null auf alle Zeilennummern passt und damit einer weggelassenen Zeilennummer entspricht.

Es können mehrere Optionen -W angegeben werden. Passt eine Warnung auf mehr als eine Option, wird die Aktion der letzten passenden Option ausgeführt. Ungültige Optionen -W werden ignoriert (allerdings wird beim Ausgeben der ersten Warnung eine Meldung über ungültige Optionen ausgegeben).

Warnungen lassen sich auch über die Umgebungsvariable PYTHONWARNINGS und innerhalb eines Python-Programms über das Modul warnings steuern. Mit der Funktion warnings.filterwarnings() kannst du zum Beispiel einen regulären Ausdruck auf die Warnmeldung anwenden.

Weitere Einzelheiten unter The Warnings Filter und Describing Warning Filters.

-x

Überspringt die erste Zeile des Quelltextes, sodass auch Nicht-Unix-Formen von #!cmd verwendet werden können.

Damit lässt sich ein Python-Skript in eine Windows-Batchdatei verwandeln. Ähnlich wie beim Hinzufügen einer Shebang-Zeile und dem Setzen des Ausführungsbits unter Unix kannst du die Endung des Python-Skripts in .bat ändern und folgende Zeile am Anfang des Skripts einfügen:

@py -x "%~f0" %* & exit /b

Oder, um den Pfad zum Python-Interpreter ausdrücklich anzugeben:

@"C:\Path\to\python.exe" -x "%~f0" %* & exit /b

Anders als eine Shebang-Zeile, die ein Python-Kommentar ist, ist diese Zeile keine gültige Python-Syntax, deshalb braucht es die Option -x, um sie zu überspringen.

-X

Für verschiedene umsetzungsspezifische Optionen reserviert. CPython definiert derzeit die folgenden möglichen Werte:

  • -X faulthandler schaltet faulthandler ein. Siehe auch PYTHONFAULTHANDLER.

    Added in version 3.3.

  • -X showrefcount gibt die Gesamtzahl der Referenzen und die Anzahl der belegten Speicherblöcke aus, wenn das Programm endet oder nach jeder Anweisung im interaktiven Interpreter. Das funktioniert nur bei Debug-Builds.

    Added in version 3.4.

  • -X tracemalloc beginnt damit, Python-Speicheranforderungen über das Modul tracemalloc mitzuschreiben. Standardmäßig wird im Traceback einer Aufzeichnung nur der jüngste Frame gespeichert. Mit -X tracemalloc=NFRAME beginnt das Mitschreiben mit einer Traceback-Grenze von NFRAME Frames. Mehr dazu unter tracemalloc.start() und PYTHONTRACEMALLOC.

    Added in version 3.4.

  • -X int_max_str_digits stellt die Längenbegrenzung bei der Umwandlung zwischen Ganzzahl und Zeichenkette ein. Siehe auch PYTHONINTMAXSTRDIGITS.

    Added in version 3.11.

  • -X importtime to show how long each import takes. It shows module name, cumulative time (including nested imports) and self time (excluding nested imports). Note that its output may be broken in multi-threaded application. Typical usage is python3 -X importtime -c 'import asyncio'. See also PYTHONPROFILEIMPORTTIME.

    Added in version 3.7.

  • -X dev: schaltet den Python-Entwicklungsmodus ein, der zusätzliche Prüfungen zur Laufzeit einführt, die zu aufwendig sind, um standardmäßig eingeschaltet zu sein. Siehe auch PYTHONDEVMODE.

    Added in version 3.7.

  • -X utf8 schaltet den Python-UTF-8-Modus ein. -X utf8=0 schaltet den Python-UTF-8-Modus ausdrücklich ab (auch wenn er sich sonst automatisch einschalten würde). Siehe auch PYTHONUTF8.

    Added in version 3.7.

  • -X pycache_prefix=PATH schreibt .pyc-Dateien in einen parallelen Baum unterhalb des angegebenen Verzeichnisses anstatt in den Codebaum. Siehe auch PYTHONPYCACHEPREFIX.

    Added in version 3.8.

  • -X warn_default_encoding löst eine EncodingWarning aus, wenn beim Öffnen von Dateien die vom Gebietsschema abhängige Standardkodierung verwendet wird. Siehe auch PYTHONWARNDEFAULTENCODING.

    Added in version 3.10.

  • -X no_debug_ranges schaltet das Mitführen der Tabellen ab, die jedem Befehl in Codeobjekten zusätzliche Ortsangaben zuordnen (Endzeile, Startspalte und Endspalte). Das ist nützlich, wenn kleinere Codeobjekte und pyc-Dateien gewünscht sind und wenn die zusätzlichen sichtbaren Ortsmarkierungen unterdrückt werden sollen, mit denen der Interpreter Tracebacks anzeigt. Siehe auch PYTHONNODEBUGRANGES.

    Added in version 3.11.

  • -X frozen_modules legt fest, ob eingefrorene Module vom Importmechanismus ignoriert werden. Der Wert on bedeutet, dass sie importiert werden, off, dass sie ignoriert werden. Standard ist on bei einem installierten Python (der Normalfall). Befindet es sich in Entwicklung (Ausführung aus dem Quellbaum), ist der Standard off. Beachte, dass die eingefrorenen Module importlib_bootstrap und importlib_bootstrap_external immer verwendet werden, auch wenn dieser Schalter auf off steht. Siehe auch PYTHON_FROZEN_MODULES.

    Added in version 3.11.

  • -X perf schaltet die Unterstützung für den Linux-Profiler perf ein. Ist diese Option angegeben, kann der Profiler perf Python-Aufrufe melden. Diese Option gibt es nur auf einigen Plattformen und sie tut nichts, wenn sie auf dem aktuellen System nicht unterstützt wird. Der Standardwert ist „off“. Siehe auch PYTHONPERFSUPPORT und Python support for the Linux perf profiler.

    Added in version 3.12.

  • -X perf_jit schaltet die Unterstützung für den Linux-Profiler perf mit DWARF-Unterstützung ein. Ist diese Option angegeben, kann der Profiler perf Python-Aufrufe anhand von DWARF-Informationen melden. Diese Option gibt es nur auf einigen Plattformen und sie tut nichts, wenn sie auf dem aktuellen System nicht unterstützt wird. Der Standardwert ist „off“. Siehe auch PYTHON_PERF_JIT_SUPPORT und Python support for the Linux perf profiler.

    Added in version 3.13.

  • -X cpu_count=n überschreibt os.cpu_count(), os.process_cpu_count() und multiprocessing.cpu_count(). n muss größer oder gleich 1 sein. Diese Option kann nützlich sein, wenn die CPU-Ressourcen eines Container-Systems begrenzt werden müssen. Siehe auch PYTHON_CPU_COUNT. Ist n gleich default, wird nichts überschrieben.

    Added in version 3.13.

  • -X presite=package.module gibt ein Modul an, das importiert werden soll, bevor das Modul site ausgeführt wird und bevor das Modul __main__ existiert. Das importierte Modul ist deshalb nicht __main__. Damit lässt sich früh während der Python-Initialisierung Code ausführen. Python muss im Debug-Modus gebaut sein, damit es diese Option gibt. Siehe auch PYTHON_PRESITE.

    Added in version 3.13.

  • -X gil=0,1 erzwingt, dass der GIL abgeschaltet beziehungsweise eingeschaltet wird. Der Wert 0 ist nur in Builds verfügbar, die mit --disable-gil konfiguriert sind. Siehe auch PYTHON_GIL und Free-threaded CPython.

    Added in version 3.13.

Außerdem lassen sich damit beliebige Werte übergeben und über das Wörterbuch sys._xoptions abrufen.

Added in version 3.2.

Geändert in Version 3.9: Die Option -X showalloccount wurde entfernt.

Geändert in Version 3.10: Die Option -X oldparser wurde entfernt.

1.1.4. Farbsteuerung

Der Python-Interpreter ist standardmäßig so eingestellt, dass er Ausgaben in bestimmten Situationen farblich hervorhebt, etwa beim Anzeigen von Tracebacks. Dieses Verhalten lässt sich über verschiedene Umgebungsvariablen steuern.

Setzt du die Umgebungsvariable TERM auf dumb, wird die Farbe abgeschaltet.

Ist die Umgebungsvariable FORCE_COLOR gesetzt, wird die Farbe unabhängig vom Wert von TERM eingeschaltet. Das ist nützlich auf CI-Systemen, die keine Terminals sind, aber dennoch ANSI-Escape-Sequenzen anzeigen können.

Ist die Umgebungsvariable NO_COLOR gesetzt, schaltet Python alle Farbe in der Ausgabe ab. Das hat Vorrang vor FORCE_COLOR.

Alle diese Umgebungsvariablen werden auch von anderen Werkzeugen zur Steuerung der Farbausgabe verwendet. Um die Farbausgabe nur im Python-Interpreter zu steuern, lässt sich die Umgebungsvariable PYTHON_COLORS verwenden. Diese Variable hat Vorrang vor NO_COLOR, das wiederum Vorrang vor FORCE_COLOR hat.

1.1.5. Options you shouldn’t use

-J

Reserved for use by Jython.

1.2. Umgebungsvariablen

Diese Umgebungsvariablen beeinflussen das Verhalten von Python. Verarbeitet werden sie vor den Befehlszeilenschaltern, mit Ausnahme von -E und -I. Üblicherweise haben Befehlszeilenschalter bei einem Widerspruch Vorrang vor Umgebungsvariablen.

PYTHONHOME

Ändert den Ort der Standard-Python-Bibliotheken. Standardmäßig werden die Bibliotheken in prefix/lib/pythonversion und exec_prefix/lib/pythonversion gesucht, wobei prefix und exec_prefix installationsabhängige Verzeichnisse sind, die beide standardmäßig /usr/local lauten.

Ist PYTHONHOME auf ein einzelnes Verzeichnis gesetzt, ersetzt dieser Wert sowohl prefix als auch exec_prefix. Um dafür unterschiedliche Werte anzugeben, setze PYTHONHOME auf prefix:exec_prefix.

PYTHONPATH

Erweitert den Standardsuchpfad für Moduldateien. Das Format entspricht dem von PATH in der Shell: ein oder mehrere Verzeichnispfade, getrennt durch os.pathsep (also Doppelpunkte unter Unix oder Semikolons unter Windows). Nicht vorhandene Verzeichnisse werden stillschweigend ignoriert.

Neben gewöhnlichen Verzeichnissen dürfen einzelne Einträge in PYTHONPATH auch auf ZIP-Dateien verweisen, die reine Python-Module enthalten (im Quelltext oder kompiliert). Erweiterungsmodule lassen sich nicht aus ZIP-Dateien importieren.

Der Standardsuchpfad ist installationsabhängig, beginnt aber in der Regel mit prefix/lib/pythonversion (siehe PYTHONHOME oben). Er wird immer an PYTHONPATH angehängt.

Ein zusätzliches Verzeichnis wird, wie oben unter Optionen der Schnittstelle beschrieben, im Suchpfad vor PYTHONPATH eingefügt. Der Suchpfad lässt sich innerhalb eines Python-Programms über die Variable sys.path verändern.

PYTHONSAFEPATH

Ist sie auf eine nicht leere Zeichenkette gesetzt, wird kein möglicherweise unsicherer Pfad an den Anfang von sys.path gestellt. Einzelheiten dazu unter der Option -P.

Added in version 3.11.

PYTHONPLATLIBDIR

Ist sie auf eine nicht leere Zeichenkette gesetzt, überschreibt sie den Wert von sys.platlibdir.

Added in version 3.9.

PYTHONSTARTUP

Ist das der Name einer lesbaren Datei, werden die Python-Befehle in dieser Datei ausgeführt, bevor im interaktiven Modus die erste Eingabeaufforderung erscheint. Die Datei wird im selben Namensraum ausgeführt, in dem auch die interaktiven Befehle ausgeführt werden, sodass darin definierte oder importierte Objekte in der interaktiven Sitzung ohne Qualifizierung verwendet werden können. Du kannst in dieser Datei auch die Eingabeaufforderungen sys.ps1 und sys.ps2 sowie den Hook sys.__interactivehook__ ändern.

Löst beim Aufruf während des Starts ein Auditing-Ereignis cpython.run_startup mit dem Dateinamen als Argument aus.

PYTHONOPTIMIZE

Ist sie auf eine nicht leere Zeichenkette gesetzt, entspricht das der Angabe der Option -O. Ist sie auf eine Ganzzahl gesetzt, entspricht das der mehrfachen Angabe von -O.

PYTHONBREAKPOINT

Ist sie gesetzt, benennt sie ein aufrufbares Objekt in Punktschreibweise. Das Modul, das dieses Objekt enthält, wird importiert, und anschließend wird das Objekt von der Standardumsetzung von sys.breakpointhook() ausgeführt, die selbst von der integrierten Funktion breakpoint() aufgerufen wird. Ist sie nicht gesetzt oder auf die leere Zeichenkette gesetzt, entspricht das dem Wert „pdb.set_trace“. Setzt du sie auf die Zeichenkette „0“, tut die Standardumsetzung von sys.breakpointhook() nichts, sondern kehrt sofort zurück.

Added in version 3.7.

PYTHONDEBUG

Ist sie auf eine nicht leere Zeichenkette gesetzt, entspricht das der Angabe der Option -d. Ist sie auf eine Ganzzahl gesetzt, entspricht das der mehrfachen Angabe von -d.

Diese Umgebungsvariable setzt einen Debug-Build von Python voraus, andernfalls wird sie ignoriert.

PYTHONINSPECT

Ist sie auf eine nicht leere Zeichenkette gesetzt, entspricht das der Angabe der Option -i.

Diese Variable lässt sich auch von Python-Code über os.environ verändern, um beim Programmende den Inspect-Modus zu erzwingen.

Löst ein Auditing-Ereignis cpython.run_stdin ohne Argumente aus.

Geändert in Version 3.12.5: (auch 3.11.10, 3.10.15, 3.9.20 und 3.8.20) Löst Auditing-Ereignisse aus.

Geändert in Version 3.13: Verwendet, wenn möglich, PyREPL. In diesem Fall wird auch PYTHONSTARTUP ausgeführt. Löst Auditing-Ereignisse aus.

PYTHONUNBUFFERED

Ist sie auf eine nicht leere Zeichenkette gesetzt, entspricht das der Angabe der Option -u.

PYTHONVERBOSE

Ist sie auf eine nicht leere Zeichenkette gesetzt, entspricht das der Angabe der Option -v. Ist sie auf eine Ganzzahl gesetzt, entspricht das der mehrfachen Angabe von -v.

PYTHONCASEOK

Ist sie gesetzt, ignoriert Python in import-Anweisungen die Groß- und Kleinschreibung. Das funktioniert nur unter Windows und macOS.

PYTHONDONTWRITEBYTECODE

Ist sie auf eine nicht leere Zeichenkette gesetzt, versucht Python nicht, beim Import von Quellmodulen .pyc-Dateien zu schreiben. Das entspricht der Angabe der Option -B.

PYTHONPYCACHEPREFIX

Ist sie gesetzt, schreibt Python .pyc-Dateien in einen gespiegelten Verzeichnisbaum unter diesem Pfad anstatt in Verzeichnisse __pycache__ innerhalb des Quellbaums. Das entspricht der Angabe der Option -X pycache_prefix=PATH.

Added in version 3.8.

PYTHONHASHSEED

Ist diese Variable nicht gesetzt oder auf random gesetzt, wird ein Zufallswert als Startwert für die Hashes von str- und bytes-Objekten verwendet.

Ist PYTHONHASHSEED auf einen ganzzahligen Wert gesetzt, wird dieser als fester Startwert verwendet, um hash() für die von der Hash-Randomisierung betroffenen Typen zu erzeugen.

Das soll wiederholbares Hashing ermöglichen, etwa für Selbsttests des Interpreters selbst, oder es mehreren Python-Prozessen in einem Verbund erlauben, dieselben Hash-Werte zu verwenden.

Die Ganzzahl muss eine Dezimalzahl im Bereich [0,4294967295] sein. Mit dem Wert 0 wird die Hash-Randomisierung abgeschaltet.

Added in version 3.2.3.

PYTHONINTMAXSTRDIGITS

Ist diese Variable auf eine Ganzzahl gesetzt, stellt sie die globale Längenbegrenzung bei der Umwandlung zwischen Ganzzahl und Zeichenkette des Interpreters ein.

Added in version 3.11.

PYTHONIOENCODING

Ist sie vor dem Start des Interpreters gesetzt, überschreibt sie die für stdin/stdout/stderr verwendete Kodierung, in der Form encodingname:errorhandler. Sowohl der Teil encodingname als auch der Teil :errorhandler ist optional und hat dieselbe Bedeutung wie in str.encode().

Bei stderr wird der Teil :errorhandler ignoriert, der Handler ist immer 'backslashreplace'.

Geändert in Version 3.4: Der Teil encodingname ist jetzt optional.

Geändert in Version 3.6: Unter Windows wird die von dieser Variable angegebene Kodierung bei interaktiven Konsolenpuffern ignoriert, sofern nicht zusätzlich PYTHONLEGACYWINDOWSSTDIO angegeben ist. Dateien und Pipes, die über die Standardströme umgeleitet werden, sind nicht betroffen.

PYTHONNOUSERSITE

Ist sie gesetzt, fügt Python das site-packages-Verzeichnis des Benutzers nicht zu sys.path hinzu.

Siehe auch

PEP 370 – site-packages-Verzeichnis pro Benutzer

PYTHONUSERBASE

Legt das Basisverzeichnis des Benutzers fest, aus dem der Pfad des site-packages-Verzeichnisses des Benutzers und die Installationspfade für python -m pip install --user berechnet werden.

Siehe auch

PEP 370 – site-packages-Verzeichnis pro Benutzer

PYTHONEXECUTABLE

Ist diese Umgebungsvariable gesetzt, wird sys.argv[0] auf ihren Wert gesetzt statt auf den Wert aus der C-Laufzeitumgebung. Funktioniert nur unter macOS.

PYTHONWARNINGS

Das entspricht der Option -W. Ist sie auf eine durch Kommas getrennte Zeichenkette gesetzt, entspricht das der mehrfachen Angabe von -W, wobei Filter, die weiter hinten in der Liste stehen, Vorrang vor früheren haben.

Die einfachsten Einstellungen wenden eine bestimmte Aktion bedingungslos auf alle Warnungen an, die ein Prozess ausgibt (auch auf die, die sonst standardmäßig ignoriert werden):

PYTHONWARNINGS=default  # Einmal pro Aufrufstelle warnen
PYTHONWARNINGS=error    # In Ausnahmen umwandeln
PYTHONWARNINGS=always   # Jedes Mal warnen
PYTHONWARNINGS=all      # Dasselbe wie PYTHONWARNINGS=always
PYTHONWARNINGS=module   # Einmal pro aufrufendem Modul warnen
PYTHONWARNINGS=once     # Einmal pro Python-Prozess warnen
PYTHONWARNINGS=ignore   # Niemals warnen

Weitere Einzelheiten unter The Warnings Filter und Describing Warning Filters.

PYTHONFAULTHANDLER

Ist diese Umgebungsvariable auf eine nicht leere Zeichenkette gesetzt, wird beim Start faulthandler.enable() aufgerufen: Es wird ein Handler für die Signale SIGSEGV, SIGFPE, SIGABRT, SIGBUS und SIGILL eingerichtet, der den Python-Traceback ausgibt. Das entspricht der Option -X faulthandler.

Added in version 3.3.

PYTHONTRACEMALLOC

Ist diese Umgebungsvariable auf eine nicht leere Zeichenkette gesetzt, werden Python-Speicheranforderungen über das Modul tracemalloc mitgeschrieben. Der Wert der Variable ist die größte Anzahl an Frames, die im Traceback einer Aufzeichnung gespeichert werden. PYTHONTRACEMALLOC=1 speichert zum Beispiel nur den jüngsten Frame. Mehr dazu bei der Funktion tracemalloc.start(). Das entspricht dem Setzen der Option -X tracemalloc.

Added in version 3.4.

PYTHONPROFILEIMPORTTIME

If this environment variable is set to a non-empty string, Python will show how long each import takes. This is equivalent to setting the -X importtime option.

Added in version 3.7.

PYTHONASYNCIODEBUG

Ist diese Umgebungsvariable auf eine nicht leere Zeichenkette gesetzt, wird der Debug-Modus des Moduls asyncio eingeschaltet.

Added in version 3.4.

PYTHONMALLOC

Legt die Python-Speicherverwalter fest und/oder richtet Debug-Hooks ein.

Legt die Familie der von Python verwendeten Speicherverwalter fest:

Debug-Hooks einrichten:

  • debug: richtet Debug-Hooks über den Standard-Speicherverwaltern ein.

  • malloc_debug: wie malloc, richtet aber zusätzlich Debug-Hooks ein.

  • pymalloc_debug: wie pymalloc, richtet aber zusätzlich Debug-Hooks ein.

  • mimalloc_debug: wie mimalloc, richtet aber zusätzlich Debug-Hooks ein.

Added in version 3.6.

Geändert in Version 3.7: Der Verwalter "default" wurde hinzugefügt.

PYTHONMALLOCSTATS

If set to a non-empty string, Python will print statistics of the pymalloc memory allocator every time a new pymalloc object arena is created, and on shutdown.

This variable is ignored if the PYTHONMALLOC environment variable is used to force the malloc() allocator of the C library, or if Python is configured without pymalloc support.

Geändert in Version 3.6: Diese Variable lässt sich jetzt auch bei einem im Release-Modus kompilierten Python verwenden. Auf eine leere Zeichenkette gesetzt, hat sie jetzt keine Wirkung.

PYTHONLEGACYWINDOWSFSENCODING

Ist sie auf eine nicht leere Zeichenkette gesetzt, kehrt der Standardmodus für Dateisystemkodierung und Fehlerbehandlung zu den Werten vor 3.6 zurück, also ‚mbcs‘ und ‚replace‘. Andernfalls werden die neuen Standardwerte ‚utf-8‘ und ‚surrogatepass‘ verwendet.

Das lässt sich zur Laufzeit auch mit sys._enablelegacywindowsfsencoding() einschalten.

Verfügbarkeit: Windows.

Added in version 3.6: Mehr dazu unter PEP 529.

PYTHONLEGACYWINDOWSSTDIO

Ist sie auf eine nicht leere Zeichenkette gesetzt, werden der neue Konsolenleser und der neue Konsolenschreiber nicht verwendet. Unicode-Zeichen werden dann gemäß der aktiven Codepage der Konsole kodiert und nicht mit utf-8.

Diese Variable wird ignoriert, wenn die Standardströme (in Dateien oder Pipes) umgeleitet werden, anstatt auf Konsolenpuffer zu verweisen.

Verfügbarkeit: Windows.

Added in version 3.6.

PYTHONCOERCECLOCALE

Ist sie auf den Wert 0 gesetzt, überspringt die Hauptanwendung der Python-Befehlszeile das Umlenken der alten ASCII-basierten Gebietsschemata C und POSIX auf eine leistungsfähigere UTF-8-basierte Alternative.

Ist diese Variable nicht gesetzt (oder auf einen anderen Wert als 0), ist außerdem die Umgebungsvariable LC_ALL zum Überschreiben des Gebietsschemas nicht gesetzt, und ist das für die Kategorie LC_CTYPE gemeldete aktuelle Gebietsschema entweder das Standard-Gebietsschema C oder das ausdrücklich ASCII-basierte POSIX, dann versucht die Python-Befehlszeile, für die Kategorie LC_CTYPE die folgenden Gebietsschemata in der angegebenen Reihenfolge einzustellen, bevor sie die Laufzeitumgebung des Interpreters lädt:

  • C.UTF-8

  • C.utf8

  • UTF-8

Gelingt es, eine dieser Gebietsschema-Kategorien einzustellen, wird die Umgebungsvariable LC_CTYPE in der aktuellen Prozessumgebung ebenfalls entsprechend gesetzt, bevor die Python-Laufzeitumgebung initialisiert wird. So wird die geänderte Einstellung nicht nur vom Interpreter selbst und von anderen gebietsschemabewussten Komponenten im selben Prozess gesehen (etwa der GNU-Bibliothek readline), sondern auch in Unterprozessen (unabhängig davon, ob darin ein Python-Interpreter läuft) sowie bei Operationen, die die Umgebung anstelle des aktuellen C-Gebietsschemas abfragen (etwa Pythons eigenes locale.getdefaultlocale()).

Das Einstellen eines dieser Gebietsschemata (ausdrücklich oder über das oben beschriebene stillschweigende Umlenken) schaltet automatisch die Fehlerbehandlung surrogateescape für sys.stdin und sys.stdout ein (sys.stderr verwendet weiterhin backslashreplace wie in jedem anderen Gebietsschema). Dieses Verhalten der Ströme lässt sich wie üblich über PYTHONIOENCODING überschreiben.

Zur Fehlersuche sorgt PYTHONCOERCECLOCALE=warn dafür, dass Python Warnmeldungen auf stderr ausgibt, wenn das Umlenken des Gebietsschemas greift oder wenn beim Initialisieren der Python-Laufzeitumgebung noch ein Gebietsschema aktiv ist, das das Umlenken ausgelöst hätte.

Beachte außerdem, dass PYTHONUTF8 auch dann standardmäßig in alten ASCII-basierten Gebietsschemata greift, wenn das Umlenken des Gebietsschemas abgeschaltet ist oder kein geeignetes Ziel-Gebietsschema findet. Beide Funktionen müssen abgeschaltet werden, damit der Interpreter für Systemschnittstellen ASCII anstelle von UTF-8 verwendet.

Verfügbarkeit: Unix.

Added in version 3.7: Mehr dazu unter PEP 538.

PYTHONDEVMODE

Ist diese Umgebungsvariable auf eine nicht leere Zeichenkette gesetzt, wird der Python-Entwicklungsmodus eingeschaltet, der zusätzliche Prüfungen zur Laufzeit einführt, die zu aufwendig sind, um standardmäßig eingeschaltet zu sein. Das entspricht dem Setzen der Option -X dev.

Added in version 3.7.

PYTHONUTF8

Auf 1 gesetzt, schaltet sie den Python-UTF-8-Modus ein.

Auf 0 gesetzt, schaltet sie den Python-UTF-8-Modus ab.

Jede andere nicht leere Zeichenkette führt beim Initialisieren des Interpreters zu einem Fehler.

Added in version 3.7.

PYTHONWARNDEFAULTENCODING

Ist diese Umgebungsvariable auf eine nicht leere Zeichenkette gesetzt, wird eine EncodingWarning ausgelöst, wenn die vom Gebietsschema abhängige Standardkodierung verwendet wird.

Einzelheiten unter Opt-in EncodingWarning.

Added in version 3.10.

PYTHONNODEBUGRANGES

Ist diese Variable gesetzt, schaltet sie das Mitführen der Tabellen ab, die jedem Befehl in Codeobjekten zusätzliche Ortsangaben zuordnen (Endzeile, Startspalte und Endspalte). Das ist nützlich, wenn kleinere Codeobjekte und pyc-Dateien gewünscht sind und wenn die zusätzlichen sichtbaren Ortsmarkierungen unterdrückt werden sollen, mit denen der Interpreter Tracebacks anzeigt.

Added in version 3.11.

PYTHONPERFSUPPORT

Ist diese Variable auf einen Wert ungleich null gesetzt, schaltet sie die Unterstützung für den Linux-Profiler perf ein, damit dieser Python-Aufrufe erkennen kann.

Auf 0 gesetzt, schaltet sie die Unterstützung für den Linux-Profiler perf ab.

Siehe auch die Befehlszeilenoption -X perf und Python support for the Linux perf profiler.

Added in version 3.12.

PYTHON_PERF_JIT_SUPPORT

Ist diese Variable auf einen Wert ungleich null gesetzt, schaltet sie die Unterstützung für den Linux-Profiler perf ein, damit dieser Python-Aufrufe anhand von DWARF-Informationen erkennen kann.

Auf 0 gesetzt, schaltet sie die Unterstützung für den Linux-Profiler perf ab.

Siehe auch die Befehlszeilenoption -X perf_jit und Python support for the Linux perf profiler.

Added in version 3.13.

PYTHON_CPU_COUNT

Ist diese Variable auf eine positive Ganzzahl gesetzt, überschreibt sie die Rückgabewerte von os.cpu_count() und os.process_cpu_count().

Siehe auch die Befehlszeilenoption -X cpu_count.

Added in version 3.13.

PYTHON_FROZEN_MODULES

Ist diese Variable auf on oder off gesetzt, legt sie fest, ob eingefrorene Module vom Importmechanismus ignoriert werden. Der Wert on bedeutet, dass sie importiert werden, off, dass sie ignoriert werden. Standard ist on bei Builds ohne Debug-Unterstützung (der Normalfall) und off bei Debug-Builds. Beachte, dass die eingefrorenen Module importlib_bootstrap und importlib_bootstrap_external immer verwendet werden, auch wenn dieser Schalter auf off steht.

Siehe auch die Befehlszeilenoption -X frozen_modules.

Added in version 3.13.

PYTHON_COLORS

Ist diese Variable auf 1 gesetzt, färbt der Interpreter verschiedene Arten von Ausgaben ein. Auf 0 gesetzt, schaltet sie dieses Verhalten ab. Siehe auch Farbsteuerung.

Added in version 3.13.

PYTHON_BASIC_REPL

If this variable is set to any value, the interpreter will not attempt to load the Python-based REPL that requires curses and readline, and will instead use the traditional parser-based REPL.

Added in version 3.13.

PYTHON_HISTORY

Mit dieser Umgebungsvariable lässt sich der Ort einer Datei .python_history festlegen (standardmäßig ist es .python_history im Benutzerverzeichnis).

Added in version 3.13.

PYTHON_GIL

Ist diese Variable auf 1 gesetzt, wird der Global Interpreter Lock (GIL) erzwungen eingeschaltet. Auf 0 gesetzt, erzwingt sie, dass der GIL abgeschaltet ist (erfordert ein Python, das mit der Build-Option --disable-gil konfiguriert ist).

Siehe auch die Befehlszeilenoption -X gil, die Vorrang vor dieser Variable hat, sowie Free-threaded CPython.

Added in version 3.13.

PYTHON_JIT

Bei Builds, in denen die experimentelle Just-in-Time-Kompilierung verfügbar ist, kann diese Variable den JIT beim Start des Interpreters erzwungen abschalten (0) oder einschalten (1).

Added in version 3.13.

1.2.1. Variablen für den Debug-Modus

PYTHONDUMPREFS

Ist sie gesetzt, gibt Python Objekte und Referenzzähler aus, die nach dem Herunterfahren des Interpreters noch leben.

Erfordert ein Python, das mit der Build-Option --with-trace-refs konfiguriert ist.

PYTHONDUMPREFSFILE

Ist sie gesetzt, gibt Python Objekte und Referenzzähler, die nach dem Herunterfahren des Interpreters noch leben, in eine Datei unter dem Pfad aus, der als Wert dieser Umgebungsvariable angegeben ist.

Erfordert ein Python, das mit der Build-Option --with-trace-refs konfiguriert ist.

Added in version 3.11.

PYTHON_PRESITE

Ist diese Variable auf ein Modul gesetzt, wird dieses Modul früh im Lebenszyklus des Interpreters importiert, bevor das Modul site ausgeführt wird und bevor das Modul __main__ erzeugt wird. Das importierte Modul wird deshalb nicht als __main__ behandelt.

Damit lässt sich früh während der Python-Initialisierung Code ausführen.

Um ein Untermodul zu importieren, verwende package.module als Wert, wie in einer import-Anweisung.

Siehe auch die Befehlszeilenoption -X presite, die Vorrang vor dieser Variable hat.

Erfordert ein Python, das mit der Build-Option --with-pydebug konfiguriert ist.

Added in version 3.13.