Die Initialisierung des Modulsuchpfads sys.path

Ein Modulsuchpfad wird beim Start von Python initialisiert. Dieser Modulsuchpfad ist unter sys.path zugänglich.

Der erste Eintrag im Modulsuchpfad ist das Verzeichnis, das das Eingabeskript enthält, falls eines vorhanden ist. Andernfalls ist der erste Eintrag das aktuelle Verzeichnis, was der Fall ist, wenn die interaktive Shell, ein Befehl -c oder ein Modul -m ausgeführt wird.

Die Umgebungsvariable PYTHONPATH wird oft verwendet, um Verzeichnisse zum Suchpfad hinzuzufügen. Wenn diese Umgebungsvariable gefunden wird, werden ihre Inhalte zum Modulsuchpfad hinzugefügt.

Hinweis

PYTHONPATH wirkt sich auf alle installierten Python-Versionen/Umgebungen aus. Seien Sie vorsichtig beim Setzen dieser Variable in Ihrem Shell-Profil oder als globale Umgebungsvariable. Das Modul site bietet nuanciertere Techniken, wie unten erwähnt.

Die nächsten hinzugefügten Elemente sind die Verzeichnisse, die Standard-Python-Module sowie alle Erweiterungsmodule enthalten, von denen diese Module abhängen. Erweiterungsmodule sind .pyd-Dateien unter Windows und .so-Dateien auf anderen Plattformen. Das Verzeichnis mit den plattformunabhängigen Python-Modulen wird als prefix bezeichnet. Das Verzeichnis mit den Erweiterungsmodulen wird als exec_prefix bezeichnet.

Die Umgebungsvariable PYTHONHOME kann verwendet werden, um die Speicherorte für prefix und exec_prefix festzulegen. Andernfalls werden diese Verzeichnisse gefunden, indem die Python-Ausführungsdatei als Startpunkt verwendet und dann nach verschiedenen „Landmark“-Dateien und Verzeichnissen gesucht wird. Beachten Sie, dass symbolische Links verfolgt werden, sodass der tatsächliche Speicherort der Python-Ausführungsdatei als Startpunkt für die Suche verwendet wird. Der Speicherort der Python-Ausführungsdatei wird als home bezeichnet.

Sobald home ermittelt wurde, wird das Verzeichnis prefix gefunden, indem zuerst nach pythonmajorversionminorversion.zip (z. B. python311.zip) gesucht wird. Unter Windows wird das Zip-Archiv in home gesucht, und unter Unix wird das Archiv in lib erwartet. Beachten Sie, dass der erwartete Speicherort des Zip-Archivs zum Modulsuchpfad hinzugefügt wird, auch wenn das Archiv nicht existiert. Wenn kein Archiv gefunden wurde, setzt Python unter Windows die Suche nach prefix fort, indem es nach Lib\os.py sucht. Python unter Unix sucht nach lib/pythonmajorversion.minorversion/os.py (z. B. lib/python3.11/os.py). Unter Windows sind prefix und exec_prefix identisch. Auf anderen Plattformen wird jedoch nach lib/pythonmajorversion.minorversion/lib-dynload (z. B. lib/python3.11/lib-dynload) gesucht und als Anker für exec_prefix verwendet. Auf einigen Plattformen kann lib auch lib64 oder ein anderer Wert sein, siehe sys.platlibdir und PYTHONPLATLIBDIR.

Nachdem sie gefunden wurden, sind prefix und exec_prefix unter sys.base_prefix bzw. sys.base_exec_prefix verfügbar.

Wenn PYTHONHOME nicht gesetzt ist und eine pyvenv.cfg-Datei neben der Hauptausführungsdatei oder in ihrem übergeordneten Verzeichnis gefunden wird, werden sys.prefix und sys.exec_prefix auf das Verzeichnis gesetzt, das pyvenv.cfg enthält. Andernfalls werden sie auf denselben Wert wie sys.base_prefix bzw. sys.base_exec_prefix gesetzt. Dies wird von Virtuellen Umgebungen verwendet.

Schließlich wird das Modul site verarbeitet und die Verzeichnisse site-packages werden dem Modulsuchpfad hinzugefügt. Eine gängige Methode zur Anpassung des Suchpfads ist die Erstellung der Module sitecustomize oder usercustomize, wie in der Dokumentation des Moduls site beschrieben.

Hinweis

Bestimmte Kommandozeilenoptionen können die Pfadberechnungen weiter beeinflussen. Siehe -E, -I, -s und -S für weitere Details.

Geändert in Version 3.14: sys.prefix und sys.exec_prefix werden nun während der Pfadinitialisierung auf das pyvenv.cfg-Verzeichnis gesetzt. Dies wurde zuvor vom Modul site übernommen und war daher von -S betroffen.

Virtuelle Umgebungen

Virtuelle Umgebungen platzieren eine Datei pyvenv.cfg in ihrem Präfix, was dazu führt, dass sys.prefix und sys.exec_prefix auf sie zeigen, anstatt auf die Basisinstallation.

Die Werte für prefix und exec_prefix der Basisinstallation sind unter sys.base_prefix und sys.base_exec_prefix verfügbar.

Neben der Verwendung als Markierung zur Identifizierung virtueller Umgebungen kann pyvenv.cfg auch zur Konfiguration der site-Initialisierung verwendet werden. Bitte beachten Sie die Dokumentation zu virtuellen Umgebungen in site.

Hinweis

PYTHONHOME überschreibt die Erkennung von pyvenv.cfg.

Hinweis

Es gibt andere Möglichkeiten, wie "virtuelle Umgebungen" implementiert werden könnten. Diese Dokumentation bezieht sich auf Implementierungen, die auf dem Mechanismus pyvenv.cfg basieren, wie z. B. venv. Die meisten Implementierungen virtueller Umgebungen folgen dem von venv vorgegebenen Modell, es kann jedoch exotische Implementierungen geben, die davon abweichen.

_pth-Dateien

Um sys.path vollständig zu überschreiben, erstellen Sie eine Datei mit dem Namen ._pth, die denselben Namen wie die gemeinsam genutzte Bibliothek oder die ausführbare Datei hat (z. B. python._pth oder python311._pth). Der Pfad der gemeinsam genutzten Bibliothek ist unter Windows immer bekannt, kann aber auf anderen Plattformen nicht verfügbar sein. In der Datei ._pth geben Sie eine Zeile für jeden Pfad an, der zu sys.path hinzugefügt werden soll. Die Datei, die auf dem Namen der gemeinsam genutzten Bibliothek basiert, überschreibt diejenige, die auf der ausführbaren Datei basiert. Dies ermöglicht es, Pfade für jedes Programm, das die Laufzeitumgebung lädt, nach Wunsch einzuschränken.

Wenn die Datei existiert, werden alle Registrierungs- und Umgebungsvariablen ignoriert, der isolierte Modus wird aktiviert und site wird nicht importiert, es sei denn, eine Zeile in der Datei gibt import site an. Leere Pfade und Zeilen, die mit # beginnen, werden ignoriert. Jeder Pfad kann absolut oder relativ zum Speicherort der Datei sein. Importanweisungen, außer für site, sind nicht gestattet, und beliebiger Code kann nicht angegeben werden.

Beachten Sie, dass .pth-Dateien (ohne führenden Unterstrich) vom Modul site normal verarbeitet werden, wenn import site angegeben wurde.

Eingebettetes Python

Wenn Python in eine andere Anwendung eingebettet ist, können Py_InitializeFromConfig() und die Struktur PyConfig zur Initialisierung von Python verwendet werden. Pfadbezogene Details sind unter Python-Pfadkonfiguration beschrieben.

Siehe auch