Renommer un fichier en Python

Pour renommer un fichier en Python, appelez os.rename(), pathlib.Path.rename() ou shutil.move() en indiquant les chemins source et destination. Utilisez os.rename() ou Path.rename() pour renommer un fichier sur le système de fichiers ; choisissez shutil.move() si la destination peut se trouver sur un autre système de fichiers. Les exemples ci-dessous créent leurs propres fichiers temporaires : ils ne dépendent donc pas du répertoire de travail et ne modifient aucun fichier de projet.

Renommer un fichier avec os.rename()

os.rename(source, destination) remplace le chemin source par le chemin destination. Construisez les chemins avec pathlib afin qu’ils soient assemblés selon les règles du système d’exploitation utilisé. Cet exemple crée un fichier dans un répertoire temporaire, puis le renomme sur place :

Exécutez cet exemple :

Le code et les libellés ou sorties affichés dans cette section restent en anglais.

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"))

En cas de succès, l’appel renvoie None. Les chemins relatifs sont interprétés depuis le répertoire de travail actuel du processus, qui peut différer de celui où se trouve votre script. Construire les chemins à partir d’un répertoire connu évite cette ambiguïté.

Renommer un fichier avec pathlib.Path.rename()

Path.rename() effectue le même type de renommage tout en représentant la source et la destination sous forme d’objets chemin. with_name() crée un chemin voisin avec un nouveau nom de fichier ; cette méthode ne renomme pas le fichier à elle seule.

Le code et les libellés ou sorties affichés dans cette section restent en anglais.

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"))

La valeur renvoyée est un Path correspondant au nouvel emplacement. Utilisez cette méthode si votre code représente déjà les chemins avec Path ; elle est soumise aux mêmes contraintes de renommage du système d’exploitation que os.rename().

Renommer ou déplacer un fichier avec shutil.move()

shutil.move(source, destination) accepte des valeurs compatibles avec les chemins et renvoie le chemin de destination sous forme de chaîne. Si un renommage sur le même système de fichiers est possible, la fonction l’utilise. Pour un déplacement entre systèmes de fichiers, elle peut copier le fichier puis supprimer la source : l’opération n’est donc pas nécessairement un renommage atomique.

Le code et les libellés ou sorties affichés dans cette section restent en anglais.

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"))

Si la destination désigne un répertoire existant, shutil.move() place la source dans ce répertoire en conservant son nom de base. Sinon, la destination est traitée comme le nouveau chemin du fichier. Vérifiez attentivement la forme de la destination lorsqu’il est possible de confondre un répertoire et un nom de fichier.

Gérer les chemins, les fichiers manquants et les destinations existantes

La source doit exister et le répertoire parent de la destination doit être accessible. Si la source ou le répertoire parent manque, une erreur FileNotFoundError est généralement levée ; les permissions, les restrictions liées aux fichiers ouverts et d’autres conditions du système de fichiers peuvent entraîner une erreur PermissionError ou une autre OSError. Interceptez les erreurs précises auxquelles votre application peut remédier et laissez les échecs inattendus apparaître. N’interceptez pas toutes les exceptions dans le seul but d’afficher un message laissant croire que l’opération a réussi.

Le comportement lorsqu’un fichier existe déjà à la destination dépend de la plateforme. Sur certains systèmes, le renommage peut remplacer le fichier existant ; sur d’autres, il échoue. Path.rename() suit la même règle sous-jacente. shutil.move() s’appuie aussi sur un renommage lorsque c’est possible et utilise une copie suivie d’une suppression entre systèmes de fichiers : ne supposez donc pas que le remplacement se comportera de la même façon sur toutes les plateformes et tous les systèmes de fichiers. Pour éviter tout remplacement, vérifiez que la destination n’existe pas avant le déplacement, en gardant à l’esprit qu’un autre processus pourrait la créer entre la vérification et l’opération. Pour une garantie plus forte, utilisez une opération exclusive propre au système d’exploitation et adaptée à votre application.

Choisir la bonne méthode

Pour un simple renommage sur un même système de fichiers, utilisez Path.rename() si le reste de votre code s’appuie sur pathlib, ou os.rename() s’il utilise déjà des chemins sous forme de chaînes ou le module os. Les deux renvoient None. Choisissez shutil.move() si le déplacement peut traverser des systèmes de fichiers ou si son comportement avec une destination qui est un répertoire vous est utile ; cette fonction renvoie le chemin de destination obtenu. Les trois méthodes exigent une source valide, et aucune ne rend atomique un déplacement réalisé en plusieurs étapes par copie puis suppression. Indiquez clairement les chemins source et destination, décidez comment votre application doit gérer les collisions et testez les comportements dépendants du système de fichiers sur les plateformes que vous prenez en charge.