Python – Deletar Arquivos e Diretórios

Este capítulo cobre todas as formas padrão de deletar arquivos e diretórios em Python — desde o módulo clássico os até a API moderna pathlib e o módulo shutil para diretórios não vazios. Você também aprenderá padrões seguros de tratamento de erros para que seu código se comporte adequadamente quando um arquivo já foi removido ou uma permissão é negada.

Deletando um Único Arquivo

Usando os.remove()

O módulo os faz parte da biblioteca padrão do Python e fornece uma interface portável para funções do sistema operacional. os.remove() deleta um único arquivo. Ele lança FileNotFoundError se o caminho não existir e PermissionError se o processo não tiver as permissões necessárias.

Deletar um arquivo com os.remove()

import os

os.remove("report.txt")

Envolva a chamada em um bloco try/except para que seu programa trate arquivos ausentes de forma adequada:

Deletar um arquivo com tratamento de erros

import os

try:
    os.remove("report.txt")
    print("File deleted.")
except FileNotFoundError:
    print("File not found — nothing to delete.")
except PermissionError:
    print("Permission denied.")

Usando pathlib.Path.unlink() (Python 3.4+)

pathlib fornece uma interface orientada a objetos para caminhos do sistema de arquivos. Path.unlink() deleta o arquivo apontado pelo caminho. Desde o Python 3.8 você pode passar missing_ok=True para suprimir FileNotFoundError automaticamente.

Deletar um arquivo com pathlib

from pathlib import Path

# Raises FileNotFoundError if the file does not exist
Path("report.txt").unlink()

Deletar um arquivo silenciosamente se não existir (Python 3.8+)

from pathlib import Path

Path("report.txt").unlink(missing_ok=True)
print("Done — file deleted or was already absent.")

missing_ok=True é a alternativa idiomática do Python 3.8+ ao padrão verificar-e-deletar. Prefira-o em vez de verificações com os.path.exists() porque evita uma condição de corrida: outro processo poderia deletar o arquivo entre sua verificação e sua chamada de deleção.

Verificando existência antes de deletar (padrão clássico)

Antes de missing_ok ser adicionado, a abordagem padrão era uma guarda com os.path.exists():

Verificar existência antes de deletar

import os

if os.path.exists("report.txt"):
    os.remove("report.txt")
else:
    print("File not found.")

Isso funciona bem para scripts onde condições de corrida não são uma preocupação, mas missing_ok=True é mais limpo em código novo.

Deletando um Diretório Vazio

os.rmdir() remove um diretório, mas apenas se estiver vazio. Ele lança OSError se o diretório contiver quaisquer arquivos ou subdiretórios.

Deletar um diretório vazio

import os

try:
    os.rmdir("empty_folder")
    print("Directory removed.")
except FileNotFoundError:
    print("Directory not found.")
except OSError:
    print("Directory is not empty or cannot be removed.")

Com pathlib, use Path.rmdir():

from pathlib import Path

Path("empty_folder").rmdir()

Deletando um Diretório Não Vazio

Para remover um diretório e tudo o que está dentro dele (arquivos, subdiretórios e seus conteúdos), use shutil.rmtree(). Isso é equivalente ao rm -rf no Unix — é permanente e irreversível.

Deletar uma árvore de diretórios

import shutil

shutil.rmtree("old_project")
print("Directory and all its contents deleted.")

Adicione tratamento de erros para os modos de falha mais comuns:

Deletar uma árvore de diretórios com segurança

import shutil

try:
    shutil.rmtree("old_project")
    print("Deleted successfully.")
except FileNotFoundError:
    print("Directory not found.")
except PermissionError:
    print("Permission denied.")

O parâmetro ignore_errors

Passe ignore_errors=True para suprimir todos os erros silenciosamente. Use isso apenas quando você genuinamente não se importa se a deleção foi bem-sucedida:

import shutil

shutil.rmtree("old_project", ignore_errors=True)

Deletando Múltiplos Arquivos que Correspondem a um Padrão

Para deletar todos os arquivos que correspondem a um padrão glob, combine pathlib.Path.glob() com unlink():

Deletar todos os arquivos .log em um diretório

from pathlib import Path

deleted = 0
for log_file in Path(".").glob("*.log"):
    log_file.unlink()
    deleted += 1
print(f"{deleted} log file(s) deleted.")

Para pesquisar subdiretórios recursivamente, use rglob():

Deletar todos os arquivos .tmp em uma árvore de diretórios

from pathlib import Path

for tmp_file in Path(".").rglob("*.tmp"):
    tmp_file.unlink(missing_ok=True)

O equivalente com o módulo os usa os.listdir() e os.remove():

Deletar todos os arquivos .txt usando os

import os

directory = "."
for filename in os.listdir(directory):
    if filename.endswith(".txt"):
        os.remove(os.path.join(directory, filename))

Sempre revise quais arquivos correspondem antes de executar uma deleção em massa. Uma rápida passagem com print() antes do loop de deleção é um hábito seguro.

Enviando Arquivos para a Lixeira (Deleção Reversível)

os.remove() e Path.unlink() deletam arquivos permanentemente — não há desfazer. Se você precisar de uma deleção reversível (enviar um arquivo para a Lixeira do sistema), instale o pacote de terceiros send2trash:

pip install send2trash

import send2trash

send2trash.send2trash("report.txt")
print("File moved to Trash.")

Isso é útil em ferramentas de desktop ou scripts onde a deleção acidental seria catastrófica.

Comparação dos Métodos de Deleção

Principais Conclusões

• Use Path.unlink(missing_ok=True) para deleção de arquivo único no Python moderno (3.8+).
• Use os.rmdir() ou Path.rmdir() apenas para diretórios vazios.
• Use shutil.rmtree() para remover um diretório e todo o seu conteúdo — verifique o caminho primeiro.
• Sempre trate FileNotFoundError e PermissionError para tornar os scripts robustos.
• Prefira send2trash quando uma deleção reversível for importante.

Capítulos Relacionados

• Manipulação de Arquivos Python — abertura, modos e a instrução with
• Python – Ler Arquivos — lendo dados de arquivos
• Python – Escrever / Criar Arquivos — escrevendo e criando arquivos
• Python Try Except — tratando exceções de forma robusta