Benennen Sie eine Datei in Python um

Um eine einzelne Datei in Python umzubenennen, rufen Sie os.rename(), pathlib.Path.rename() oder shutil.move() mit dem Quell- und dem Zielpfad auf. Verwenden Sie os.rename() oder Path.rename() für eine Umbenennung im Dateisystem. Wählen Sie shutil.move(), wenn sich das Ziel möglicherweise auf einem anderen Dateisystem befindet. Die folgenden Beispiele erstellen ihre temporären Dateien selbst. Sie sind daher unabhängig vom aktuellen Arbeitsverzeichnis und ändern keine Projektdatei.

Eine Datei mit os.rename() umbenennen

os.rename(source, destination) ändert den Quellpfad in den Zielpfad. Erstellen Sie Pfade mit pathlib, damit sie nach den Regeln des aktuellen Betriebssystems zusammengesetzt werden. Dieses Beispiel erstellt eine Datei in einem temporären Verzeichnis und benennt sie dort um:

Führen Sie dieses Beispiel aus:

Der Code und die angezeigten Bezeichnungen oder Ausgaben in diesem Abschnitt bleiben auf Englisch.

import os
from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    source = Path(folder) / "draft.txt"
    destination = Path(folder) / "final.txt"
    source.write_text("Report", encoding="utf-8")
    os.rename(source, destination)
    print(destination.name, destination.read_text(encoding="utf-8"))

Bei erfolgreichem Aufruf wird None zurückgegeben. Relative Pfade beziehen sich auf das aktuelle Arbeitsverzeichnis des Prozesses, das sich vom Verzeichnis Ihres Skripts unterscheiden kann. Wenn Sie Pfade ausgehend von einem bekannten Verzeichnis erstellen, vermeiden Sie diese Unklarheit.

Eine Datei mit pathlib.Path.rename() umbenennen

Path.rename() führt dieselbe Art von Umbenennung aus, wobei Quell- und Zielpfad als Pfadobjekte dargestellt werden. with_name() erstellt einen benachbarten Pfad mit einem neuen Dateinamen; die Datei selbst wird dadurch nicht umbenannt.

Der Code und die angezeigten Bezeichnungen oder Ausgaben in diesem Abschnitt bleiben auf Englisch.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    source = Path(folder) / "draft.txt"
    source.write_text("Report", encoding="utf-8")
    destination = source.with_name("final.txt")
    renamed_path = source.rename(destination)
    print(renamed_path.name, renamed_path.read_text(encoding="utf-8"))

Zurückgegeben wird ein Path für den neuen Speicherort. Verwenden Sie diese Methode, wenn Ihr Code Pfade bereits mit Path darstellt. Für sie gelten dieselben betriebssystemspezifischen Einschränkungen beim Umbenennen wie für os.rename().

Eine Datei mit shutil.move() umbenennen oder verschieben

shutil.move(source, destination) akzeptiert pfadähnliche Werte und gibt den Zielpfad als Zeichenfolge zurück. Wenn eine Umbenennung auf demselben Dateisystem möglich ist, wird diese verwendet. Beim Verschieben zwischen Dateisystemen kann die Funktion die Datei kopieren und anschließend die Quelldatei entfernen. Das Verschieben ist daher nicht unbedingt eine atomare Umbenennung.

Der Code und die angezeigten Bezeichnungen oder Ausgaben in diesem Abschnitt bleiben auf Englisch.

import shutil
from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    source = Path(folder) / "draft.txt"
    destination = Path(folder) / "final.txt"
    source.write_text("Report", encoding="utf-8")
    moved_to = shutil.move(source, destination)
    print(Path(moved_to).name, Path(moved_to).read_text(encoding="utf-8"))

Bezeichnet das Ziel ein vorhandenes Verzeichnis, legt shutil.move() die Quelldatei unter Verwendung ihres Basisnamens darin ab. Andernfalls wird das Ziel als neuer Dateipfad behandelt. Prüfen Sie genau, was das Ziel bezeichnet, wenn Verzeichnis und Dateiname leicht verwechselt werden können.

Pfade, fehlende Dateien und vorhandene Ziele behandeln

Die Quelldatei muss vorhanden und das übergeordnete Verzeichnis des Ziels verfügbar sein. Für eine fehlende Quelle oder ein fehlendes übergeordnetes Verzeichnis wird häufig FileNotFoundError ausgelöst. Berechtigungsprobleme, Einschränkungen durch geöffnete Dateien und andere Dateisystembedingungen können PermissionError oder einen anderen OSError auslösen. Fangen Sie gezielt die Fehler ab, von denen sich Ihre Anwendung erholen kann, und lassen Sie unerwartete Fehler sichtbar werden. Fangen Sie nicht einfach jede Ausnahme ab, nur um eine Erfolgsmeldung auszugeben.

Das Verhalten bei einer bereits vorhandenen Zieldatei hängt vom Betriebssystem ab. Auf manchen Systemen kann eine Umbenennung eine vorhandene Datei ersetzen, auf anderen schlägt sie fehl. Für Path.rename() gilt dieselbe zugrunde liegende Regel. shutil.move() verwendet nach Möglichkeit ebenfalls eine Umbenennung und arbeitet beim Wechsel zwischen Dateisystemen mit Kopieren und anschließendem Entfernen. Gehen Sie deshalb nicht von einem einheitlichen Überschreibverhalten auf allen Plattformen und Dateisystemen aus. Wenn vorhandene Dateien nicht überschrieben werden sollen, prüfen Sie vor dem Verschieben, ob das Ziel fehlt. Beachten Sie dabei, dass ein anderer Prozess es zwischen Prüfung und Vorgang erstellen könnte. Für stärkere Garantien verwenden Sie eine für Ihre Anwendung geeignete betriebssystemspezifische exklusive Operation.

Die passende Methode auswählen

Für eine einfache Umbenennung auf einem Dateisystem verwenden Sie Path.rename(), wenn Ihr übriger Code pathlib nutzt, oder os.rename(), wenn er bereits mit Zeichenfolgenpfaden oder dem Modul os arbeitet. Beide geben None zurück. Wählen Sie shutil.move(), wenn ein Verschieben Dateisystemgrenzen überschreiten könnte oder das Verhalten bei einem Verzeichnis als Ziel nützlich ist. Diese Funktion gibt den resultierenden Zielpfad zurück. Bei allen drei Methoden muss die Quelle gültig sein; keine davon macht ein mehrstufiges Kopieren und Entfernen atomar. Geben Sie Quell- und Zielpfad ausdrücklich an, legen Sie fest, wie Ihre Anwendung mit vorhandenen Zielen umgehen soll, und testen Sie dateisystemabhängiges Verhalten auf den von Ihnen unterstützten Plattformen.