Como renomear arquivos com Python usando uma simulação segura

Aprenda a renomear imagens com Python: confira o plano antes de aplicar, detecte conflitos de nomes e registre as mudanças em uma pasta de cópias.

Equipe Próxima Habilidade · Atualizado em 2026-10-15 · 16 min de leitura

Renomear dezenas de arquivos pode ser uma tarefa repetitiva, mas um programa curto também consegue repetir um erro em segundos. Por isso, o primeiro objetivo deste tutorial é produzir uma lista de mudanças que você possa conferir. A execução vem depois, em uma pasta de cópias, com nomes de destino verificados e um registro das operações realizadas.

Vamos trabalhar com imagens de um pequeno catálogo. O resultado desejado é transformar nomes variados em uma sequência como catalogo-001.jpg e catalogo-002.png, mantendo a extensão de cada arquivo. O exemplo usa Python 3.12 ou superior e apenas a biblioteca padrão. Ele atua somente nos arquivos diretamente dentro da pasta indicada, sem entrar em subpastas.

O que a simulação faz e o que ela não faz

Uma simulação calcula os nomes novos e os mostra na tela sem executar a renomeação. Assim você consegue perceber uma pasta errada, uma ordem inesperada ou um destino já existente antes de alterar qualquer arquivo. Simular é especialmente útil quando o padrão de nomes será aplicado a documentos que depois precisam ser encontrados por outra pessoa.

Simulação não é backup. Ela também não protege contra mudanças feitas por outro programa entre a conferência e a execução. Neste tutorial, trabalhe em uma pasta exclusiva de cópias e feche programas que possam modificá-la. Não use o exemplo em pastas sincronizadas, compartilhadas ou de produção sem adaptar o controle de concorrência.

O programa não edita o conteúdo das imagens, não muda formatos e não corrige arquivos danificados. Trocar a extensão de PNG para JPG, por exemplo, não converte a imagem. Aqui preservamos a extensão justamente para separar duas tarefas diferentes: alterar o nome e transformar o arquivo.

Prepare uma pasta pequena de trabalho

Crie uma pasta chamada amostra-fotos e copie para ela quatro ou cinco imagens sem importância operacional. Mantenha os originais em outro lugar. Use nomes fáceis de reconhecer, como frente.jpg, detalhe.png e embalagem.jpeg. Acrescente um arquivo de texto para confirmar que o filtro não vai selecioná-lo.

Antes de abrir o terminal, confira onde essa pasta está. No Windows, você pode copiar o caminho pela barra de endereços do Explorador de Arquivos. Caminhos com espaços precisam ser colocados entre aspas no comando. Evite começar a experiência na pasta Downloads inteira, porque ela costuma misturar arquivos com finalidades e proprietários diferentes.

Faça uma lista simples dos nomes atuais. Você poderá compará-la com a simulação e com o resultado final. Se uma imagem não abrir antes do teste, não use esse arquivo para avaliar o programa. O exercício deve isolar a lógica de renomeação, sem confundi-la com um problema anterior de armazenamento ou de formato.

Entenda as partes de um caminho

Um caminho identifica onde está um arquivo. Em Python, pathlib permite representar esse caminho com um objeto Path e combinar pasta e nome sem montar manualmente as barras do sistema. A documentação oficial de pathlib descreve recursos como name, suffix e iterdir, usados no exemplo.

Para um arquivo chamado embalagem.final.jpg, name representa o nome completo e suffix retorna .jpg. O programa preserva esse sufixo e acrescenta a sequência no início do novo nome. Nomes com vários pontos continuam possíveis, mas apenas a última extensão será mantida. Arquivos compactados, como .tar.gz, não fazem parte do filtro deste tutorial.

O caminho da pasta também precisa ser validado. Um texto que parece um diretório pode apontar para um arquivo ou para um local inexistente. A mensagem de erro deve aparecer antes de qualquer mudança. O programa também recusa uma pasta fornecida como link simbólico e imagens que sejam links simbólicos, para manter o exercício restrito aos arquivos da pasta de teste.

Defina o padrão antes de programar

Nosso padrão tem três partes: o prefixo catalogo-, um número com pelo menos três posições e a extensão original em letras minúsculas. O primeiro arquivo selecionado vira catalogo-001; o segundo, catalogo-002. Quando a quantidade passa de 999, o formato continua mostrando o número completo, sem cortá-lo.

A sequência depende da ordenação dos nomes antigos, não da data da fotografia. O programa ordena por nome sem diferenciar maiúsculas de minúsculas e usa o nome original como critério adicional. Isso torna a ordenação explícita. Ela é uma ordenação textual: imagem10 pode aparecer antes de imagem2. Se a ordem comercial importar, corrija os nomes ou monte uma lista manual antes de aplicar.

Arquivos cujo nome já começa com catalogo- ficam fora da seleção. Isso evita renomear novamente as saídas de uma execução concluída. Porém, um desses arquivos pode ocupar o destino que seria necessário para outro. Nessa situação, o programa interrompe a preparação. Ele não tenta adivinhar se deve continuar a numeração, substituir o arquivo ou reorganizar o catálogo.

Por que verificar todos os destinos

A documentação de os.rename explica que o comportamento diante de um destino existente varia entre sistemas. Uma rotina que parece segura no Windows pode substituir um arquivo em outro ambiente. Por isso, verificar apenas se o primeiro destino está livre não é suficiente.

O plano inteiro precisa passar pela conferência antes de começar. Imagine que catalogo-001.jpg está livre, mas catalogo-003.png já existe. Se o programa verificar um destino por vez enquanto renomeia, ele poderá alterar os dois primeiros arquivos e parar no terceiro. A preparação antecipada detecta esse conflito sem iniciar a sequência.

Ainda existe uma janela entre a checagem e a operação. O exemplo não implementa uma transação nem garante segurança sob concorrência. Essa limitação precisa orientar o uso: pasta de cópias, acesso exclusivo e conferência. Para processos empresariais, seriam necessários controles adicionais, testes no sistema de arquivos utilizado e uma estratégia de recuperação adequada ao ambiente.

O programa completo

Salve o código abaixo como renomear_imagens.py fora da pasta amostra-fotos. Use um editor de texto e confirme que o arquivo termina em .py, não em .py.txt. O código usa um arquivo de registro chamado renomeacao-log.jsonl dentro da pasta de trabalho. Se esse registro já existir, uma nova aplicação será recusada para preservar o histórico.

"""Renomeia imagens em uma pasta exclusiva de copias. Simulacao por padrao."""
import argparse
import json
from pathlib import Path

EXTENSOES = {".jpg", ".jpeg", ".png"}
PREFIXO = "catalogo-"
LOG = "renomeacao-log.jsonl"

def construir_plano(pasta):
    pasta = Path(pasta).expanduser()
    if pasta.is_symlink() or not pasta.is_dir():
        raise ValueError("Informe uma pasta real e existente, sem link simbolico.")
    pasta = pasta.resolve()
    entradas = list(pasta.iterdir())
    imagens = []
    for item in entradas:
        if item.suffix.lower() not in EXTENSOES:
            continue
        if item.is_symlink():
            raise ValueError(f"Link simbolico recusado: {item.name}")
        if item.is_file() and not item.name.casefold().startswith(PREFIXO):
            imagens.append(item)
    imagens.sort(key=lambda p: (p.name.casefold(), p.name))
    ocupados = {p.name.casefold() for p in entradas}
    destinos = set()
    plano = []
    for numero, origem in enumerate(imagens, 1):
        destino = pasta / f"{PREFIXO}{numero:03d}{origem.suffix.lower()}"
        chave = destino.name.casefold()
        if chave in ocupados or chave in destinos:
            raise ValueError(f"Destino ja existe ou se repete: {destino.name}")
        destinos.add(chave)
        plano.append((origem, destino))
    return pasta, plano

def aplicar_plano(pasta, plano):
    # Reconfere antes de iniciar. Nao e uma transacao nem protege concorrencia.
    ocupados = {p.name.casefold() for p in pasta.iterdir()}
    for origem, destino in plano:
        if origem.is_symlink() or not origem.is_file():
            raise ValueError(f"Origem mudou: {origem.name}")
        if destino.name.casefold() in ocupados:
            raise ValueError(f"Destino ocupado: {destino.name}")
    with (pasta / LOG).open("x", encoding="utf-8", newline="\n") as registro:
        def anotar(dados):
            registro.write(json.dumps(dados, ensure_ascii=False) + "\n")
            registro.flush()
        anotar({"plano": [[a.name, b.name] for a, b in plano]})
        for origem, destino in plano:
            # Verificacao adicional; exige pasta sem outros escritores.
            if destino.exists() or destino.is_symlink():
                raise ValueError(f"Destino surgiu: {destino.name}")
            origem.rename(destino)
            anotar({"concluido": [origem.name, destino.name]})

def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("pasta")
    parser.add_argument("--aplicar", action="store_true")
    args = parser.parse_args()
    try:
        pasta, plano = construir_plano(args.pasta)
        print(f"Pasta: {pasta}")
        if not plano:
            print("Nenhuma imagem selecionada.")
            return 0
        for origem, destino in plano:
            print(f"{origem.name} -> {destino.name}")
        if not args.aplicar:
            print("SIMULACAO: nenhum arquivo alterado.")
            return 0
        if input("Confira o plano. Digite RENOMEAR para aplicar: ").strip() != "RENOMEAR":
            print("Cancelado. Nenhum arquivo renomeado.")
            return 0
        aplicar_plano(pasta, plano)
        print(f"Concluido: {len(plano)} arquivo(s). Registro: {LOG}")
        return 0
    except (OSError, ValueError) as erro:
        print(f"Erro: {erro}")
        print("Se a aplicacao iniciou, confira o registro e os nomes atuais.")
        return 1

if __name__ == "__main__":
    raise SystemExit(main())

O código fica dividido entre construir o plano e aplicá-lo. Isso permite testar a seleção e os conflitos sem modificar imagens. O parâmetro --aplicar é necessário para sair do modo de simulação, e a confirmação RENOMEAR acrescenta uma pausa de conferência. Nenhum desses recursos substitui o cuidado com a pasta escolhida.

Execute primeiro sem alterar arquivos

No terminal, entre na pasta onde você salvou o programa. No Windows com Python disponível pelo lançador, use o comando abaixo. Se sua instalação usa python em vez de py, substitua apenas o nome do executável. Não copie o caminho de exemplo sem adaptá-lo ao seu computador.

py -3 renomear_imagens.py "C:/Fotos/amostra-fotos"

A saída deve mostrar pares de nome antigo e nome novo, seguidos da indicação de simulação. Compare cada linha com a pasta no Explorador. Confira a quantidade de arquivos, as extensões e a ordem. O arquivo de texto usado como controle deve continuar fora da lista, assim como as subpastas.

Se nenhuma imagem aparecer, verifique a pasta informada e os sufixos aceitos. O programa seleciona JPG, JPEG e PNG, independentemente de a extensão original estar em maiúsculas. Ele não inclui WebP, HEIC ou PDF. Para ampliar o conjunto, altere a lista de extensões depois de entender a lógica e repita todos os testes em cópias.

Confira três coisas antes de aplicar

Primeiro, confirme a identidade da pasta. Dois diretórios podem ter nomes parecidos, especialmente em cópias de segurança. Leia o caminho absoluto exibido pelo programa e compare com a pasta aberta. A confirmação digitada não verifica isso por você: ela apenas impede uma aplicação acidental causada por esquecer qual modo está usando.

Segundo, confirme o significado da ordem. Se as imagens precisam representar frente, verso e detalhe nessa sequência, uma ordenação alfabética pode não atender ao objetivo. Renomear corretamente segundo o código não significa organizar corretamente segundo o seu catálogo. Ajuste a regra antes de executar, em vez de tentar corrigir a sequência de memória depois.

Terceiro, confira se os arquivos originais continuam guardados. Abra uma imagem da cópia e uma do conjunto original. Uma pasta com atalhos não equivale a uma cópia de conteúdo. O programa recusa links simbólicos selecionados, mas o procedimento de preparação ainda precisa ser feito com atenção pelo usuário.

Aplique e leia o registro

Depois de conferir a simulação, execute o mesmo comando com --aplicar. O programa recalcula o plano, mostra os pares novamente e pede a palavra de confirmação. Se você responder qualquer outra coisa, ele encerra sem renomear. Digite a palavra somente depois de confirmar que não houve mudança inesperada na pasta.

py -3 renomear_imagens.py "C:/Fotos/amostra-fotos" --aplicar

O registro JSONL guarda um objeto JSON por linha. Há uma linha com o plano e linhas de conclusão das operações. Isso facilita identificar quais mudanças foram confirmadas antes de uma eventual interrupção. O registro contém nomes de arquivos e deve acompanhar o conjunto de trabalho se esses nomes forem importantes para sua organização.

Não apague o registro apenas para forçar uma segunda execução. Leia o que aconteceu e compare com os arquivos presentes. Em uma aplicação parcial, alguns nomes já começam com catalogo- e serão ignorados na seleção seguinte; os destinos restantes podem produzir conflitos. A escolha segura para este exercício é preparar outra pasta a partir dos originais preservados.

O que fazer se aparecer um conflito

Uma mensagem de destino existente informa que um nome novo já está ocupado. O programa compara os nomes ignorando diferenças de caixa para evitar um conjunto ambíguo ao trocar de sistema. Catalogo-001.JPG e catalogo-001.jpg são tratados como colisão para este exercício, mesmo que um sistema específico permita ambos.

Abra a pasta e identifique o arquivo que ocupa o destino. Não escolha substituir automaticamente. Pode ser uma imagem de uma execução anterior ou um arquivo que alguém já organizou. Em uma pasta de teste, o caminho mais simples costuma ser começar de novo com uma cópia limpa dos originais. Em trabalho real, é necessário decidir um padrão que mantenha a rastreabilidade.

Também pode surgir uma colisão entre dois destinos planejados se você alterar o código de forma inadequada. Por exemplo, remover o contador e usar sempre catalogo.jpg cria o mesmo nome para todos os arquivos JPG. A conferência do plano deve continuar existindo depois de qualquer personalização, mesmo quando a lista parece pequena e previsível.

Como recuperar uma execução interrompida

Uma sequência de renomeações não é uma operação única. Se faltar permissão no meio do processo ou se a unidade ficar indisponível, uma parte pode ter sido concluída. O programa registra as operações após cada renomeação, mas uma interrupção exatamente entre a mudança e a gravação do log pode deixar um estado que exige conferência manual.

Por isso, não execute o comando repetidamente tentando ver se “agora vai”. Preserve o log, faça uma lista dos nomes atuais e compare com o plano registrado. Para o exercício proposto, use os originais guardados para recriar a pasta de teste. Isso evita uma tentativa de reversão que introduza novos conflitos.

Uma reversão automatizada precisaria verificar novamente cada origem e destino, considerar arquivos que surgiram depois e registrar suas próprias alterações. Não basta inverter duas colunas e executar. Se os arquivos forem únicos ou indispensáveis, pare a experimentação e trabalhe sobre cópias antes de projetar essa etapa adicional.

Testes que você pode reproduzir

Comece com três imagens e um arquivo TXT. Rode a simulação e confirme que os quatro nomes continuam iguais, embora apenas as imagens apareçam no plano. Depois aplique na cópia, confira a sequência e abra as imagens resultantes. Compare o tamanho e, se souber calcular, o hash dos arquivos antes e depois: a renomeação não deveria modificar os bytes.

Em outra pasta de teste, crie uma imagem chamada catalogo-001.jpg junto de uma chamada frente.jpg. O programa deve recusar o plano sem renomear frente.jpg. Esse cenário testa um comportamento mais importante que apenas verificar uma execução sem erros: impedir uma alteração quando a condição de segurança não está satisfeita.

Teste também uma pasta vazia, um caminho inexistente e uma subpasta contendo imagens. A pasta vazia deve informar ausência de itens; o caminho inexistente deve gerar erro compreensível; a subpasta não deve ser percorrida. Anote o resultado esperado antes de executar. Um teste é mais útil quando você sabe qual comportamento está conferindo.

Adapte o prefixo com cuidado

Você pode querer um nome relacionado à coleção, como ceramica- ou campanha-outubro-. Para uma primeira adaptação, altere a constante PREFIXO no programa e repita o conjunto de testes. Mantenha o prefixo sem barras, dois-pontos ou outros caracteres que tenham significado especial em caminhos. Prefira letras, números e hífen.

Observe que o prefixo também é usado para excluir arquivos já processados. Alterar o nome em apenas um ponto da lógica pode fazer a seleção e os destinos discordarem. A constante existe para manter essas duas decisões alinhadas. Se decidir oferecer o prefixo como argumento, valide-o antes de montar qualquer caminho.

Não acrescente dados sensíveis ao nome apenas porque eles facilitam sua identificação. Nomes podem aparecer em anexos, links, backups e registros. Um código interno de produto costuma ser mais adequado que o nome completo de um cliente. O padrão deve ajudar quem usa o conjunto sem expor informação desnecessária.

Quando usar uma planilha em vez de uma sequência

Uma numeração simples atende a um conjunto pequeno em que a ordem já está definida. Quando cada imagem precisa receber um código específico de produto, uma tabela de correspondência pode ser melhor. Nesse caso, cada linha teria nome atual e nome desejado, e o programa verificaria se toda origem existe e se nenhum destino se repete.

Essa solução exige mais validações: linhas vazias, extensão preservada, nomes duplicados, caracteres inválidos e caminhos fora da pasta autorizada. Não adapte o tutorial aceitando qualquer texto de uma planilha como destino. Um valor com separadores de pasta poderia fazer o programa sair do diretório previsto.

Para avançar nessa direção, comece pelo guia de leitura de CSV com ponto e vírgula e vírgula decimal em Python. Ele trata da interpretação da tabela, enquanto este artigo trata da alteração de nomes. Combine as etapas somente depois de conseguir testá-las separadamente.

Organização depois da renomeação

Mantenha uma pasta com os originais e outra com as imagens preparadas para uso. O log ajuda a explicar a transformação entre elas. Se você mover apenas as imagens finais para outro computador, guarde uma cópia do registro junto do material administrativo, para não perder a relação com os nomes anteriores.

Renomear arquivos também não define a ordem de exibição de um site. Uma galeria pode ordenar por nome, data, posição cadastrada ou outro campo. Confira o resultado no destino final antes de concluir que a sequência numérica controla a apresentação. O nome deve ser uma ajuda de organização, não uma suposição sobre o funcionamento de outro sistema.

Se o próximo passo for enviar anexos, revise destinatário, seleção e tamanho dos arquivos separadamente. O artigo sobre envio de e-mails com anexos usando Python aborda outra etapa de automação. Um processo confiável mantém pontos de conferência entre operações diferentes, em vez de juntar tudo em um comando difícil de revisar.

Perguntas frequentes

Posso usar o programa diretamente nos arquivos originais?

O fluxo deste tutorial foi pensado para cópias em uma pasta exclusiva. Use esse ambiente para aprender e testar. Aplicar uma rotina de alteração em arquivos únicos exige uma estratégia de backup e recuperação que vai além do exemplo. O fato de uma simulação parecer correta não elimina falhas de permissão, interrupções ou concorrência.

O programa converte JPEG em PNG?

Não. Ele preserva a extensão, normalizando apenas suas letras para minúsculas. O conteúdo continua no formato anterior. Conversão de imagem é outra operação e precisa de uma biblioteca apropriada, parâmetros de qualidade e conferência visual. Não tente converter formatos apenas trocando o sufixo do nome.

Posso deixar uma pasta de sincronização aberta?

Não use este exemplo em uma pasta modificada simultaneamente por sincronizadores ou outros usuários. O plano pode deixar de corresponder ao conteúdo real entre a conferência e a operação. Faça uma cópia local exclusiva, aplique as mudanças nela e depois revise como o conjunto será transferido ao destino.

Fontes e continuidade

As APIs foram conferidas na documentação de pathlib do Python 3.12 e na referência de os.rename. O programa, os cenários de teste e o roteiro de conferência são exemplos editoriais próprios. Explore a categoria Tecnologia e Programação para continuar com exercícios que resolvam tarefas pequenas e verificáveis.