Verificar se um arquivo existe em Python: os.path, pathlib e try/except

A resposta curta

Para verificar se um arquivo existe, use os.path.isfile() da biblioteca padrão. Ela retorna True quando o caminho aponta para um arquivo comum que existe e False caso contrário. Nunca lança erro para um caminho que não existe.

import os

# Create one file so the example has something to find.
with open("notes.txt", "w") as f:
    f.write("hello\n")

print(os.path.isfile("notes.txt"))    # True
print(os.path.isfile("missing.txt"))  # False

Os caminhos são relativos à pasta onde o programa roda (o diretório de trabalho atual), a menos que você passe um caminho absoluto como /home/ada/notes.txt ou C:\Users\Ada\notes.txt.

O resto desta página cobre as outras formas de fazer a pergunta, como elas diferem e o caso em que você não deveria fazê-la.

os.path.exists vs isfile vs isdir

O módulo os.path tem três verificações parecidas, e elas respondem perguntas um pouco diferentes:

A diferença aparece assim que um diretório entra na história:

import os

os.makedirs("reports", exist_ok=True)
with open("reports/summary.txt", "w") as f:
    f.write("all good\n")

for path in ["reports", "reports/summary.txt", "reports/old.txt"]:
    print(path, os.path.exists(path), os.path.isfile(path), os.path.isdir(path))

Saída:

reports True False True
reports/summary.txt True True False
reports/old.txt False False False

os.path.exists("reports") é True mesmo sendo reports uma pasta. Se o seu código vai ler o caminho como arquivo, exists é a verificação errada: um diretório passaria nela, e open("reports") falharia depois (com IsADirectoryError no Linux e no macOS, PermissionError no Windows). Escolha isfile quando você quer um arquivo e isdir quando quer uma pasta.

Mais dois detalhes sobre essas três funções de os.path:

• Um link simbólico é seguido. Um link que aponta para um arquivo real conta como arquivo; um link quebrado (o alvo sumiu) retorna False nas três.
• Se o Python não tem permissão para olhar dentro de uma pasta, a verificação retorna False em vez de lançar PermissionError. False quer dizer "não encontrado ou inacessível", não estritamente "não existe".

Verificando com pathlib

pathlib é a API de caminhos orientada a objetos da biblioteca padrão, e a maior parte do código novo usa ela. Um objeto Path tem as mesmas três verificações como métodos:

from pathlib import Path

folder = Path("reports")
folder.mkdir(exist_ok=True)

summary = folder / "summary.txt"
summary.write_text("all good\n")

print(summary.exists())    # True
print(summary.is_file())   # True
print(summary.is_dir())    # False
print(folder.is_dir())     # True
print((folder / "old.txt").exists())  # False

Path.exists(), Path.is_file() e Path.is_dir() se comportam como os.path.exists, isfile e isdir. O operador / junta partes do caminho com o separador certo para o sistema operacional, então folder / "summary.txt" funciona igual no Windows, no macOS e no Linux. Veja manipulação de arquivos para ler e escrever por meio de objetos Path.

Qual usar? Se o resto do seu código já passa objetos Path de um lado para outro, fique com o pathlib. Se você trabalha com strings simples e funções de os, os.path.isfile é igualmente correto. As respostas são as mesmas.

Por que verificar antes pode ser a escolha errada

O motivo mais comum para verificar se um arquivo existe é abri-lo logo depois:

import os

if os.path.isfile("config.txt"):
    with open("config.txt") as f:      # the file might be gone by now
        settings = f.read()
else:
    settings = ""

Isso tem uma brecha. Entre a chamada de isfile() e a chamada de open(), outro programa, outra thread ou o próprio usuário pode apagar ou renomear o arquivo. A verificação disse True, a abertura falha mesmo assim, e o programa quebra com FileNotFoundError de qualquer jeito. Essa brecha se chama condição de corrida, ou "time of check to time of use" (momento da verificação contra momento do uso). É rara no seu notebook e bem menos rara num servidor movimentado onde vários processos dividem uma pasta.

A solução é pular a verificação separada e deixar o próprio open() ser a verificação. O Python lança FileNotFoundError quando o arquivo não existe, e você trata isso no except:

def read_settings(path):
    try:
        with open(path) as f:
            return f.read().strip()
    except FileNotFoundError:
        return "(no settings file, using defaults)"

with open("config.txt", "w") as f:
    f.write("theme=dark\n")

print(read_settings("config.txt"))
print(read_settings("other.txt"))

Saída:

theme=dark
(no settings file, using defaults)

Agora há uma operação em vez de duas, então não há corrida possível. Esse estilo tem nome na comunidade Python: EAFP, "easier to ask forgiveness than permission" (é mais fácil pedir perdão do que permissão). O estilo oposto, verificar antes, é LBYL, "look before you leap" (olhe antes de pular). O Python prefere EAFP para trabalhar com arquivos porque o sistema operacional é o único que sabe a resposta no momento em que você abre o arquivo.

FileNotFoundError não é a única coisa que pode dar errado. Um caminho que é um diretório lança IsADirectoryError (PermissionError no Windows), e um arquivo que você não pode ler lança PermissionError. As três são subclasses de OSError, então except OSError: pega de uma vez todos os casos de "não consegui abrir". A página de exceções explica como escolher entre capturar um erro específico e capturar uma família inteira.

Quando uma verificação simples basta

Verificar antes não é errado em todos os casos. É a ferramenta certa quando você só precisa da resposta e não vai mexer no arquivo na linha seguinte:

• escolher qual mensagem mostrar ("3 jogos salvos encontrados")
• validar um caminho que o usuário digitou antes de começar um trabalho longo
• pular um trabalho que já foi feito, quando uma resposta desatualizada só custa uma repetição

A regra prática: se você vai abrir, ler, escrever ou apagar o arquivo, faça isso dentro de try. Se só quer saber, isfile() ou Path.is_file() servem.

Criar um arquivo só se ele não existir

A pergunta inversa também aparece: "escreva este arquivo, mas nunca sobrescreva um que já existe". A versão óbvia tem a mesma corrida de antes:

if not os.path.exists("report.txt"):
    with open("report.txt", "w") as f:   # another process may create it first
        f.write("new report\n")

O modo "x" (criação exclusiva) faz os dois passos em um. Ele cria o arquivo, ou lança FileExistsError se o nome já estiver ocupado:

import os

if os.path.exists("report.txt"):
    os.remove("report.txt")   # start from a clean folder for the demo

for attempt in [1, 2]:
    try:
        with open("report.txt", "x") as f:
            f.write("first version\n")
        print(f"attempt {attempt}: created report.txt")
    except FileExistsError:
        print(f"attempt {attempt}: report.txt already exists, left it alone")

Saída:

attempt 1: created report.txt
attempt 2: report.txt already exists, left it alone

Para pastas, os.makedirs(path, exist_ok=True) e Path(path).mkdir(parents=True, exist_ok=True) criam o diretório e qualquer pasta pai que falte, e não fazem nada se ele já existir. Não precisa chamar isdir() antes.

Erros comuns

• Usar exists() quando você quer um arquivo. Um diretório com o mesmo nome passa na verificação. Use isfile() ou Path.is_file().
• Esquecer de onde partem os caminhos relativos. "data.txt" é procurado no diretório de trabalho atual, que é de onde você iniciou o programa, não necessariamente a pasta onde está o script. Para achar um arquivo ao lado do script, monte o caminho a partir de Path(__file__).parent.
• Verificar e depois abrir. O arquivo pode mudar nesse meio tempo. Abra dentro de try e trate FileNotFoundError.
• Capturar qualquer exceção. except Exception: em volta de open() também esconde erros de digitação e bugs no código que lê o arquivo. Capture FileNotFoundError ou OSError.