Skip to content

Entendendo o pycache no Python: Tudo o que você precisa saber

Kana Mikami
Name
Kana Mikami

Updated on

Se você já executou um script Python, talvez tenha notado uma pasta chamada __pycache__ aparecendo dentro do seu projeto. Ela pode parecer pouco importante, mas desempenha um papel crítico em como o Python executa seus programas de forma eficiente. Neste guia, vamos explicar o que é a pasta __pycache__, por que o Python a gera e como você pode gerenciá‑la ou removê‑la com segurança.

Python é uma linguagem interpretada, mas não reinterpreta cada arquivo .py do zero toda vez que você o executa. Em vez disso, o Python compila seu código‑fonte em bytecode — uma representação leve e de baixo nível que pode ser executada mais rapidamente. Esses arquivos de bytecode compilados (com extensão .pyc) são armazenados dentro da pasta __pycache__.

Quer criar rapidamente Data Visualization a partir de um DataFrame do Python Pandas sem escrever código?

PyGWalker é uma biblioteca Python para Exploratory Data Analysis com Visualização.
PyGWalker (opens in a new tab) transforma seu pandas ou polars dataframe em uma interface estilo Tableau diretamente dentro do Jupyter Notebook.

PyGWalker for Data visualization (opens in a new tab)

O que é pycache no Python?

A pasta __pycache__ é criada automaticamente quando o Python executa um módulo. Dentro dela, o Python armazena arquivos .pyc — uma versão compilada em bytecode do seu arquivo .py.

O bytecode é projetado para execução mais rápida. Quando você executa um script, o Python procura por um arquivo .pyc atualizado:

  • Se ele existir e corresponder ao código‑fonte atual → o Python carrega imediatamente o arquivo .pyc.
  • Caso contrário → o Python recompila o código‑fonte, gera um novo arquivo .pyc e o armazena em __pycache__.

Por que os nomes de arquivos parecem module.cpython-310.pyc

As versões modernas do Python incluem uma identificação do interpretador (por exemplo, cpython-311) para que várias versões do Python possam coexistir sem conflitos.

Isso é especialmente importante ao usar:

  • Virtual environments
  • Python do sistema + Python específico de um ambiente
  • Ferramentas como pyenv, conda ou imagens Docker

Onde a pasta pycache fica localizada?

A pasta __pycache__ aparece no mesmo diretório do módulo Python que está sendo executado.

Estrutura de exemplo:


my_project/
main.py
utils.py
**pycache**/
main.cpython-311.pyc
utils.cpython-311.pyc

Se você importar um módulo de outro diretório, esse diretório também gerará seu próprio __pycache__.

Em virtual environments

Virtual environments geralmente contêm muitas pastas __pycache__ dentro dos pacotes instalados. Isso é normal — imports de pacotes geram arquivos .pyc no primeiro uso.

Como o pycache acelera scripts Python?

Executar um script Python normalmente exige:

  1. Analisar o texto (parsing)
  2. Construir uma Abstract Syntax Tree (AST)
  3. Compilar a AST em bytecode
  4. Executar o bytecode

As etapas 1–3 são ignoradas quando o Python encontra um arquivo .pyc atualizado. Por isso:

  • A primeira execução pode ser um pouco mais lenta
  • As execuções seguintes são mais rápidas (especialmente em bases de código grandes)

Arquivos pyc baseados em hash (PEP 552)

As versões modernas do Python suportam:

  • .pyc baseados em timestamp (padrão)
  • .pyc baseados em hash (para builds reprodutíveis, empacotamento, imagens Docker)

Isso torna a geração de bytecode mais estável em ambientes automatizados ou conteinerizados.

Posso deletar a pasta pycache?

Sim — excluir __pycache__ é seguro.

O Python irá recriá‑la automaticamente na próxima vez que você executar seus scripts. A única desvantagem: a próxima execução pode ser ligeiramente mais lenta devido à recompilação.

Para remover recursivamente todas as pastas __pycache__:

find . -type d -name __pycache__ -exec rm -r {} \+

Casos de uso comuns para deletar pycache

  • Depurar problemas de import
  • Após renomear/realocar módulos
  • Ao empacotar para deployment
  • Para reduzir ruído antes de um commit no Git ou de um build Docker

Como desabilitar a criação de arquivos pycache?

Você pode desabilitar a criação de .pyc definindo a variável de ambiente:

export PYTHONDONTWRITEBYTECODE=1

Quando essa opção está ativada:

  • O Python não gerará arquivos .pyc
  • Pastas __pycache__ não serão criadas

Isso é comumente usado em:

  • Imagens Docker (para reduzir o tamanho das camadas)
  • Pipelines de CI
  • Scripts pequenos em que performance é irrelevante

Para tornar essa configuração permanente, adicione a variável ao seu arquivo de configuração do shell (por exemplo, ~/.bashrc).

Como ignorar arquivos pycache no Git

Como arquivos .pyc são específicos da máquina e gerados automaticamente, eles não devem ser armazenados no controle de versão.

Adicione isto ao seu .gitignore:

__pycache__/
*.pyc

A regra *.pyc é opcional, mas útil quando versões legadas do Python colocam .pyc ao lado do .py.

O que acontece se eu deletar a pasta pycache?

Nada quebra. Seu script será executado normalmente.

O Python simplesmente:

  1. Detecta que o .pyc está faltando
  2. Recompila o arquivo .py
  3. Recria o diretório __pycache__ e o arquivo .pyc

Somente a primeira execução após a exclusão é um pouco mais lenta.

FAQ

1. Qual é o propósito da pasta __pycache__ no Python?

A pasta armazena arquivos .pyc de bytecode compilado, que fazem o Python iniciar mais rápido em execuções subsequentes.

2. Posso deletar a pasta __pycache__?

Sim. Excluí‑la é seguro. O Python a recria automaticamente.

3. Como posso ignorar arquivos __pycache__ no Git?

Adicione isto ao seu .gitignore:

__pycache__/
*.pyc