Python PermissionError [Errno 13]: como corrigir caminho, arquivo bloqueado e permissões

O erro PermissionError: [Errno 13] Permission denied informa que o sistema operacional recusou uma operação solicitada pelo Python. A causa pode ser permissão insuficiente, tentativa de abrir uma pasta como arquivo, documento bloqueado por outro programa, diretório protegido, usuário diferente em serviço ou substituição de arquivo sem direito de escrita.

Executar tudo como administrador pode esconder o sintoma e aumentar o impacto de um bug. Este guia mostra como identificar operação, caminho e usuário, reproduzir o caso em pasta descartável, diferenciar leitura de escrita, tratar arquivos temporários e corrigir o desenho com permissões mínimas.

Legenda: o sistema avalia a operação solicitada, o objeto e a identidade do processo antes de permitir o acesso.

Leia a última linha e a operação que falhou

PermissionError: [Errno 13] Permission denied: 'relatorios'

O texto mostra o caminho, mas não explica sozinho se ele é arquivo ou pasta. Leia a linha do seu código imediatamente acima. open, replace, unlink, mkdir e rename exigem permissões diferentes.

Registre caminho absoluto e operação, sem conteúdo sensível:

from pathlib import Path

caminho = Path("relatorios")
print("resolvido:", caminho.resolve())
print("existe:", caminho.exists())
print("arquivo:", caminho.is_file())
print("pasta:", caminho.is_dir())

Não publique caminhos contendo nome de usuário ou estrutura interna sem revisão.

O caso mais comum: abrir uma pasta como arquivo

open("relatorios", "w", encoding="utf-8")

Se relatorios já é diretório, o sistema recusa. Informe um nome de arquivo:

from pathlib import Path

pasta = Path("relatorios")
pasta.mkdir(parents=True, exist_ok=True)
arquivo = pasta / "resultado.txt"
arquivo.write_text("processamento concluído\n", encoding="utf-8")

Valide tipos antes de escrever. Um parâmetro chamado saida pode receber ora pasta, ora arquivo; documente o contrato e rejeite entrada ambígua.

Reproduza em uma pasta descartável

from pathlib import Path
import tempfile

with tempfile.TemporaryDirectory() as d:
    raiz = Path(d)
    pasta = raiz / "dados"
    pasta.mkdir()
    try:
        pasta.write_text("teste", encoding="utf-8")
    except PermissionError as erro:
        print(type(erro).__name__, erro.filename)

O laboratório não depende de diretórios protegidos. Em alguns sistemas, abrir pasta como arquivo pode produzir outro subtipo de OSError; trate a intenção, não apenas um número.

Descubra o diretório de trabalho real

Caminhos relativos dependem de onde o processo foi iniciado:

from pathlib import Path

print("cwd:", Path.cwd())
print("script:", Path(__file__).resolve())

IDE, serviço e tarefa agendada podem usar outra pasta. Se o arquivo pertence ao projeto, construa caminho a partir de uma base definida:

BASE = Path(__file__).resolve().parent
SAIDA = BASE / "saidas" / "resultado.csv"

Para dados do usuário, prefira pasta de dados apropriada ao sistema, configurada explicitamente. Não presuma que a pasta do programa é gravável após instalação.

Verifique qual usuário executa o processo

O terminal interativo pode ter acesso que o serviço não possui. Em Unix:

import getpass, os
print("usuario:", getpass.getuser())
print("uid:", os.getuid() if hasattr(os, "getuid") else "n/a")

No Windows, getpass.getuser() ajuda, mas serviços podem usar contas próprias. Verifique a identidade no gerenciador de serviços ou tarefa, sem alterar para uma conta privilegiada como atalho.

Conceda acesso somente à pasta necessária e documente proprietário, grupo e finalidade.

Leitura, criação e substituição exigem direitos diferentes

Ler um arquivo exige acesso ao arquivo e travessia das pastas. Criar um novo arquivo depende da pasta pai. Substituir ou renomear costuma depender das permissões do diretório, mesmo que o arquivo existente seja legível.

from pathlib import Path

destino = Path("saidas/relatorio.txt")
print("pai existe:", destino.parent.exists())
print("destino existe:", destino.exists())

Não baseie segurança apenas em os.access: o estado pode mudar entre verificação e operação. Tente a operação, capture a exceção específica e apresente mensagem útil.

Arquivo aberto no Excel ou em outro programa

No Windows, alguns programas mantêm bloqueio que impede substituir o arquivo. Feche a planilha e confirme que não existe visualização ou processo usando-a. Evite tentar dezenas de vezes em laço rápido.

Uma espera limitada pode tratar bloqueio transitório:

import time
from pathlib import Path

def substituir_com_tentativas(origem, destino, tentativas=4):
    origem, destino = Path(origem), Path(destino)
    for numero in range(tentativas):
        try:
            origem.replace(destino)
            return
        except PermissionError:
            if numero == tentativas - 1:
                raise
            time.sleep(0.5 * (numero + 1))

Se a política exige arquivo fechado, diga isso ao usuário. Retentativa não corrige pasta protegida.

Escrita atômica reduz arquivos incompletos

Escreva em temporário na mesma pasta e substitua após sucesso:

from pathlib import Path
import os, tempfile

def salvar_texto(destino, conteudo):
    destino = Path(destino)
    destino.parent.mkdir(parents=True, exist_ok=True)
    with tempfile.NamedTemporaryFile(
        "w", encoding="utf-8", dir=destino.parent, delete=False
    ) as f:
        f.write(conteudo)
        temporario = Path(f.name)
    try:
        os.replace(temporario, destino)
    except Exception:
        temporario.unlink(missing_ok=True)
        raise

Usar a mesma pasta aumenta a chance de a substituição permanecer no mesmo sistema de arquivos. Ainda é necessário direito de escrita no diretório.

Legenda: o destino só é substituído depois que o conteúdo temporário foi gravado com sucesso.

Não use chmod 777 como solução automática

Permissão ampla permite que qualquer usuário modifique o conteúdo. Em servidor, isso pode expor dados ou código. Identifique proprietário e grupo e conceda apenas leitura, escrita ou travessia necessárias.

Em Unix, comandos de inspeção incluem ls -ld pasta e namei -l caminho, quando disponível. Alterações de proprietário e modo devem seguir a administração do ambiente. Não execute comandos copiados com sudo sem compreender o alvo.

No Windows, confira a guia Segurança e permissões herdadas. Pastas sincronizadas e rede podem ter regras adicionais.

Caminhos de rede, nuvem e sincronização

Compartilhamentos podem desconectar, mudar credenciais ou bloquear arquivos. Pastas sincronizadas podem manter arquivos apenas online ou disputar renomeações. Teste primeiro em pasta local do usuário; se funciona, investigue a camada remota.

Não copie dados confidenciais para local apenas para depurar sem autorização. Use arquivo fictício e mantenha o mesmo padrão de nome e tamanho quando relevante.

Registre se o caminho é UNC, unidade mapeada, montagem ou pasta local. Serviços Windows podem não enxergar a mesma unidade mapeada da sessão interativa.

Antivírus e proteção contra ransomware

Proteções podem bloquear gravação em pastas controladas. Não desative antivírus como primeiro teste. Consulte o histórico de bloqueios e assine ou autorize o aplicativo pelo procedimento oficial da organização.

Se apenas o executável empacotado falha, mas python script.py funciona, compare identidade, reputação e pasta. Crie uma exceção mínima somente após confirmar que o programa é confiável.

Capture PermissionError com contexto útil

from pathlib import Path

def ler_config(caminho):
    caminho = Path(caminho)
    try:
        return caminho.read_text(encoding="utf-8")
    except PermissionError as erro:
        raise RuntimeError(
            f"Sem permissão para ler o arquivo de configuração: {caminho.name}"
        ) from erro

Preserve a causa com from erro. Mostre ao usuário o nome necessário, não toda a estrutura. Não capture Exception e continue com dados vazios; isso esconde configuração ausente.

Processamento em lote sem perder tudo

Ao percorrer muitos arquivos, registre falhas individualmente e continue apenas se a regra permite:

from pathlib import Path

falhas = []
for arquivo in Path("entrada").glob("*.txt"):
    try:
        texto = arquivo.read_text(encoding="utf-8")
    except PermissionError:
        falhas.append(arquivo.name)
        continue
    # processar texto

print("arquivos sem acesso:", falhas)

Não silencie falhas. O resultado deve informar que o lote ficou parcial e impedir publicação automática quando completude for obrigatória.

Testes de regressão

Use tempfile e unittest.mock para simular falha de forma portável, pois permissões reais variam entre Windows e Unix. Teste mensagem, preservação do destino e limpeza do temporário.

Para organizar o fluxo, use o criador de fluxogramas, a biblioteca Python e as ferramentas do IATechNerds.

Checklist final

Antes de alterar permissões, monte uma matriz de operações: leitura, criação, renomeação e remoção de um temporário criado pelo próprio processo. Se leitura funciona e criação falha, investigue a pasta pai. Se criação funciona e substituição falha apenas para um nome existente, procure bloqueio, propriedade ou política específica do destino.

Serviços paralelos não devem compartilhar o mesmo nome temporário. Duas tarefas gravando resultado.tmp podem bloquear ou substituir uma à outra. Use tempfile, mantenha o arquivo na pasta controlada e faça a troca somente após a escrita terminar. Bibliotecas de Excel, PDF e imagem também precisam fechar seus escritores antes da renomeação.

Em interface gráfica, traduza o diagnóstico em ação: “Feche resultado.xlsx e tente novamente” é melhor que exibir apenas Errno 13. Quando a pasta é protegida, permita escolher outro destino. Não peça que o usuário execute todo o aplicativo como administrador.

Uma fila de escrita pode ser mais previsível que várias retentativas concorrentes. Trabalhadores preparam dados e um escritor controla nomes, temporários e substituições. Registre início, sucesso, duração e nome interno, sem conteúdo do documento.

Permissões podem mudar durante a execução por unidade desmontada, credencial expirada, pasta removida ou política corporativa. Uma verificação anterior não garante a operação futura. Capture a exceção no ponto da escrita e preserve o arquivo anterior.

Links simbólicos também merecem atenção. Uma pasta aparentemente interna pode apontar para outro local. Defina se links são permitidos e nunca amplie rotinas de remoção para fora da raiz autorizada.

Teste nomes longos, Unicode, arquivo existente, destino ausente e cancelamento. O resultado correto inclui limpeza do temporário, manutenção do original e mensagem específica. A correção está completa quando funciona com permissões normais e falha de maneira segura quando o acesso não existe.

Uma auditoria sustentável responde: qual conta escreve, em qual pasta, quais extensões, por quanto tempo ficam temporários e quem lê o resultado? Documentar isso evita o mesmo problema em serviços e tarefas agendadas.

Mantenha ainda um teste de inicialização que confirme a pasta configurada sem criar arquivos reais. Ele deve falhar cedo quando o destino é inválido e orientar a correção antes do primeiro processamento importante.

Quando a falha ocorre somente em produção, compare o ambiente em uma tabela: usuário, diretório atual, caminho absoluto, tipo do sistema de arquivos, modo de abertura e existência do destino. Não copie o arquivo real para o relatório; basta registrar metadados redigidos. Diferenças como execução dentro de contêiner, volume somente leitura ou pasta montada explicam muitos casos.

Em contêineres, confirme se o volume foi montado como ro e se o UID do processo corresponde ao proprietário esperado. A imagem pode funcionar sem volume e falhar quando o host substitui a pasta. Corrija o mapeamento e a identidade, não execute o contêiner privilegiado.

Aplicações que oferecem “salvar como” devem validar extensão e confirmar sobrescrita. Crie o temporário somente depois da escolha final e não deixe que duas janelas usem o mesmo destino. Se a substituição falhar, mantenha o temporário identificável para recuperação controlada ou remova-o conforme a política.

Para arquivos de configuração, leitura negada não deve ser tratada como configuração vazia. Isso pode iniciar o sistema com padrões inseguros ou incorretos. Interrompa com mensagem clara e indique o nome do arquivo e a conta que precisa de acesso, sem revelar valores.

Métricas úteis incluem quantidade de PermissionError por operação, pasta lógica, versão e duração até a falha. Um aumento após implantação aponta para identidade ou caminho alterado. Não use o caminho completo como rótulo de métrica, pois cria alta cardinalidade e pode expor informação.

Por fim, revise a recuperação após queda de energia ou encerramento. Temporários antigos devem ter estado e idade verificáveis. Limpeza automática precisa operar somente dentro de pasta dedicada, com padrão rígido e log de itens removidos. Nunca faça uma busca ampla pelo disco baseada apenas na extensão .tmp.

• operação e caminho absoluto foram identificados;
• arquivo e diretório não foram confundidos;
• diretório de trabalho real foi confirmado;
• usuário do processo foi verificado;
• pasta pai possui o acesso necessário;
• bloqueio por outro programa foi considerado;
• caminhos de rede e sincronização foram isolados;
• proteções do sistema não foram desativadas às cegas;
• escrita crítica usa temporário e substituição;
• erros preservam causa e não expõem caminhos;
• lote parcial é sinalizado;
• nenhuma permissão ampla foi aplicada como atalho.

Documentação primária

• Python — exceções PermissionError e OSError
• Python — pathlib
• Python — open
• Python — tempfile
• Python — os.replace

Nota de produção

Rascunho autoral orientado à busca “Python PermissionError Errno 13 como resolver”. Os exemplos usam pastas temporárias e permissões mínimas. A revisão humana deve testar Windows e Unix, revisar mensagens e conferir os links antes de publicar.