Cambiar el nombre de un archivo en Python

Para cambiar el nombre de un archivo en Python, llama a os.rename(), pathlib.Path.rename() o shutil.move() con las rutas de origen y destino. Usa os.rename() o Path.rename() para cambiar el nombre en el sistema de archivos; elige shutil.move() si el destino podría estar en otro sistema de archivos. Los ejemplos siguientes crean sus propios archivos temporales, así que no dependen de un directorio de trabajo concreto ni modifican archivos de un proyecto.

Cambiar el nombre de un archivo con os.rename()

os.rename(source, destination) cambia la ruta de origen por la ruta de destino. Construye las rutas con pathlib para que se unan según las reglas del sistema operativo actual. Este ejemplo crea un archivo dentro de un directorio temporal y le cambia el nombre allí:

Ejecuta este ejemplo:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

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

La llamada devuelve None cuando se completa correctamente. Las rutas relativas se interpretan desde el directorio de trabajo actual del proceso, que puede ser distinto del directorio donde está el script. Construir las rutas a partir de un directorio conocido evita esa ambigüedad.

Cambiar el nombre de un archivo con pathlib.Path.rename()

Path.rename() realiza el mismo tipo de cambio de nombre y mantiene el origen y el destino como objetos de ruta. with_name() crea una ruta hermana con un nombre de archivo nuevo; por sí solo, no cambia el nombre del archivo.

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

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

El valor devuelto es un Path que representa la nueva ubicación. Usa este método si tu código ya representa las rutas con Path; está sujeto a las mismas restricciones del sistema operativo que os.rename().

Cambiar el nombre o mover un archivo con shutil.move()

shutil.move(source, destination) acepta valores compatibles con rutas y devuelve la ruta de destino como una cadena. Si es posible cambiar el nombre dentro del mismo sistema de archivos, realiza esa operación. Si el movimiento cruza sistemas de archivos, puede copiar el archivo y luego eliminar el original, por lo que no necesariamente es un cambio de nombre atómico.

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

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 el destino indica un directorio existente, shutil.move() coloca el archivo de origen dentro de ese directorio y conserva su nombre base. En caso contrario, interpreta el destino como la nueva ruta. Comprueba cuidadosamente qué tipo de destino estás indicando cuando se podría confundir un directorio con un nombre de archivo.

Gestionar las rutas, los archivos inexistentes y los destinos existentes

El archivo de origen debe existir y el directorio padre del destino debe estar disponible. Si falta el origen o el directorio padre, suele producirse un FileNotFoundError; los permisos, las restricciones sobre archivos abiertos y otras condiciones del sistema de archivos pueden producir un PermissionError u otro OSError. Captura los errores concretos de los que pueda recuperarse tu aplicación y deja visibles los fallos inesperados. No captures cualquier excepción solo para mostrar un mensaje que parezca indicar que todo salió bien.

El comportamiento cuando ya existe un archivo de destino depende de la plataforma. En algunos sistemas, el cambio de nombre puede reemplazar un archivo existente; en otros, falla. Path.rename() sigue la misma regla subyacente. shutil.move() también recurre al cambio de nombre cuando es posible y, si el movimiento cruza sistemas de archivos, puede copiar el archivo y eliminar el original; por eso, no des por sentado que el resultado al sobrescribir será igual en todas las plataformas y sistemas de archivos. Si necesitas evitar sobrescrituras, comprueba que el destino no exista antes de mover el archivo, teniendo en cuenta que otro proceso podría crearlo entre la comprobación y la operación. Para obtener garantías más sólidas, utiliza una operación exclusiva específica del sistema operativo que se ajuste a tu aplicación.

Elegir el método adecuado

Para cambiar el nombre de un archivo dentro de un mismo sistema de archivos, usa Path.rename() si el resto del código utiliza pathlib, o os.rename() si ya utiliza rutas como cadenas o el módulo os. Ambos devuelven None. Elige shutil.move() si el movimiento podría cruzar los límites de un sistema de archivos o si te resulta útil su comportamiento con destinos que son directorios; devuelve la ruta de destino resultante. Los tres métodos requieren que el archivo de origen sea válido, y ninguno hace atómico un movimiento que implique varios pasos de copia y eliminación. Especifica claramente las rutas de origen y destino, decide cómo debe gestionar tu aplicación los conflictos y prueba el comportamiento que dependa del sistema de archivos en las plataformas que admitas.