El error FileNotFoundError en Python aparece cuando un programa intenta abrir, leer, mover, renombrar o eliminar un archivo que no existe en la ruta utilizada. En muchos casos el archivo sí está guardado en el ordenador, pero el script busca desde otro directorio, utiliza una extensión diferente o construye una ruta incompatible con el entorno donde se ejecuta.
La solución correcta no consiste en capturar la excepción y continuar sin entenderla. Primero debes comprobar la ruta efectiva, el directorio de trabajo, el nombre del archivo y el momento en que debería haberse creado.
Ejemplo básico
with open("report.txt", encoding="utf-8") as file:
content = file.read()Si report.txt no se encuentra en el directorio actual, Python genera un mensaje parecido a:
FileNotFoundError: [Errno 2] No such file or directoryLa documentación oficial de FileNotFoundError explica que esta excepción representa un intento de acceder a una ruta inexistente.
Comprobar el directorio actual
from pathlib import Path
print(Path.cwd())Una ruta relativa se interpreta desde el directorio de trabajo, no necesariamente desde la carpeta que contiene el script. Un editor, una tarea programada, un notebook o un servidor pueden iniciar el proceso desde otra ubicación.
La documentación oficial de pathlib describe la construcción y resolución de rutas en diferentes sistemas operativos. La guía interna de pathlib en Python ofrece ejemplos adicionales de lectura, escritura y navegación.
Construir la ruta desde el archivo del script
from pathlib import Path
BASE_DIR = Path(__file__).resolve().parent
DATA_FILE = BASE_DIR / "data" / "report.txt"
with DATA_FILE.open(encoding="utf-8") as file:
content = file.read()Este patrón evita depender de la carpeta desde la que se ejecuta el comando. resolve() produce una ruta absoluta y parent selecciona la carpeta del archivo actual.
Comprobar si la ruta existe
from pathlib import Path
path = Path("data/report.txt")
print(path.exists())
print(path.is_file())
print(path.is_dir())
print(path.resolve())exists() comprueba cualquier entrada. is_file() y is_dir() distinguen archivos y carpetas. Mostrar la ruta absoluta suele revelar inmediatamente que el programa está buscando en un lugar inesperado.
Crear carpetas antes de escribir
from pathlib import Path
output = Path("reports") / "monthly.txt"
output.parent.mkdir(
parents=True,
exist_ok=True,
)
output.write_text(
"Informe generado\n",
encoding="utf-8",
)El modo de escritura puede crear el archivo, pero no crea automáticamente las carpetas intermedias. parents=True crea toda la jerarquía ausente y exist_ok=True evita un error cuando ya existe.
Revisar nombre, extensión y mayúsculas
Comprueba que el archivo no tenga una extensión oculta, como report.txt.txt. En sistemas que distinguen mayúsculas y minúsculas, Report.csv y report.csv son nombres diferentes.
from pathlib import Path
folder = Path("data")
if folder.is_dir():
for path in folder.iterdir():
print(repr(path.name))repr() ayuda a detectar espacios finales, caracteres invisibles y diferencias de capitalización.
Evitar barras manuales
# Frágil
path = folder + "/" + filename
# Portable
path = Path(folder) / filenameEn Windows, una string normal también puede interpretar secuencias como \n o \t. Pathlib evita gran parte de estos problemas y hace que el código sea más legible.
Leer archivos de texto de forma segura
from pathlib import Path
path = Path("notes.txt")
try:
content = path.read_text(encoding="utf-8")
except FileNotFoundError:
print(f"No existe el archivo: {path.resolve()}")
else:
print(content)La guía de archivos de texto en Python explica lectura, escritura, append, codificación y procesamiento línea por línea.
Capturar la excepción en la capa correcta
Una función de bajo nivel puede dejar que la excepción continúe o añadir información que facilite el diagnóstico:
from pathlib import Path
def load_template(path):
path = Path(path)
try:
return path.read_text(encoding="utf-8")
except FileNotFoundError as error:
raise FileNotFoundError(
f"No se encontró la plantilla: {path.resolve()}"
) from errorEl encadenamiento conserva el traceback original. La guía de try y except en Python explica captura específica, else, finally y raise from.
Utilizar un valor predeterminado solamente cuando sea válido
from pathlib import Path
import json
DEFAULT_CONFIG = {
"theme": "light",
"page_size": 20,
}
path = Path("config.json")
if path.is_file():
config = json.loads(
path.read_text(encoding="utf-8")
)
else:
config = DEFAULT_CONFIG.copy()Esta estrategia funciona cuando el archivo es opcional. No la utilices para ocultar la ausencia de una base de datos, plantilla o certificado obligatorio.
Buscar archivos con glob()
from pathlib import Path
files = list(Path("incoming").glob("*.csv"))
if not files:
print("No se encontraron archivos CSV")
else:
for path in files:
print(path)Una búsqueda resulta más adecuada que asumir un nombre fijo cuando los archivos incluyen fechas, identificadores o sufijos generados por otro sistema.
Mover y renombrar archivos
from pathlib import Path
source = Path("incoming/report.csv")
target = Path("processed/report.csv")
target.parent.mkdir(parents=True, exist_ok=True)
if not source.is_file():
raise FileNotFoundError(
f"No existe el origen: {source.resolve()}"
)
source.replace(target)La guía del módulo os en Python muestra operaciones adicionales con archivos, carpetas, permisos y variables de entorno.
Docker, servidores y tareas programadas
Una ruta disponible en tu ordenador puede faltar dentro de un contenedor. Comprueba qué archivos fueron copiados, cuál es el directorio de trabajo y qué volúmenes están montados.
WORKDIR /app
COPY config/ /app/config/
COPY src/ /app/src/Un script ejecutado por cron o Task Scheduler también puede comenzar en otra carpeta. Utiliza rutas absolutas derivadas de __file__ y registra la ruta resuelta, sin incluir contenido sensible.
Utilizar with para cerrar archivos
with open(
"data/report.txt",
encoding="utf-8",
) as file:
for line in file:
print(line.rstrip())La guía de with en Python explica context managers, cierre automático y varios recursos.
Pruebas con archivos temporales
from pathlib import Path
from tempfile import TemporaryDirectory
with TemporaryDirectory() as folder:
path = Path(folder) / "sample.txt"
path.write_text("example", encoding="utf-8")
assert path.read_text(encoding="utf-8") == "example"Las pruebas no deberían depender de archivos personales ni carpetas permanentes. Los directorios temporales permiten preparar y eliminar datos automáticamente.
Script de diagnóstico
from pathlib import Path
path = Path("data/report.txt")
print("Directorio actual:", Path.cwd())
print("Ruta recibida:", path)
print("Ruta absoluta:", path.resolve())
print("Existe:", path.exists())
print("Es archivo:", path.is_file())
print("Carpeta padre existe:", path.parent.exists())Procedimiento recomendado
- Imprime la ruta absoluta.
- Comprueba
Path.cwd(). - Revisa nombre, extensión y mayúsculas.
- Comprueba si la carpeta padre existe.
- Construye la ruta desde
__file__. - Verifica Docker, tareas programadas o volúmenes.
- Captura la excepción solamente cuando puedas responder correctamente.
Errores frecuentes
- Suponer que una ruta relativa parte del archivo del script.
- Concatenar barras manualmente.
- No crear carpetas intermedias.
- Ignorar mayúsculas y extensiones.
- Capturar FileNotFoundError y continuar con datos incompletos.
- Usar una ruta local dentro de Docker o producción.
- Depender de archivos personales en pruebas.
Conclusión
FileNotFoundError se resuelve observando la ruta que Python utiliza realmente. Comprueba el directorio actual, utiliza pathlib, crea carpetas antes de escribir y deriva rutas estables desde __file__. Captura la excepción solo cuando exista una alternativa válida o cuando puedas añadir un mensaje más útil.
