Skip to content

Entendiendo pycache en Python: Todo lo que necesitas saber

Kana Mikami
Name
Kana Mikami

Updated on

Si alguna vez has ejecutado un script de Python, probablemente habrás notado una carpeta llamada __pycache__ dentro de tu proyecto. Puede parecer poco importante, pero cumple un papel fundamental en cómo Python ejecuta tus programas de forma eficiente. En esta guía, veremos qué es la carpeta __pycache__, por qué Python la genera y cómo puedes gestionarla o eliminarla de forma segura.

Python es un lenguaje interpretado, pero no vuelve a interpretar cada archivo .py desde cero cada vez que lo ejecutas. En su lugar, Python compila tu código fuente a bytecode, una representación ligera y de bajo nivel que puede ejecutarse más rápidamente. Estos archivos de bytecode compilados (con la extensión .pyc) se almacenan dentro de la carpeta __pycache__.

¿Quieres crear rápidamente visualizaciones de datos desde un DataFrame de Python Pandas sin escribir código?

PyGWalker es una librería de Python para Análisis Exploratorio de Datos con visualización.
PyGWalker (opens in a new tab) convierte tu pandas o polars dataframe en una interfaz tipo Tableau directamente dentro de Jupyter Notebook.

PyGWalker for Data visualization (opens in a new tab)

¿Qué es pycache en Python?

La carpeta __pycache__ se crea automáticamente cuando Python ejecuta un módulo. Dentro de ella, Python almacena archivos .pyc, que son una versión compilada en bytecode de tu archivo .py.

El bytecode está diseñado para una ejecución más rápida. Cuando ejecutas un script, Python busca un archivo .pyc actualizado:

  • Si existe y coincide con el código fuente actual → Python carga el archivo .pyc inmediatamente.
  • Si no → Python recompila el código fuente, genera un nuevo archivo .pyc y lo guarda en __pycache__.

Por qué los nombres de archivo se ven como module.cpython-310.pyc

Las versiones modernas de Python incluyen una etiqueta del intérprete (por ejemplo, cpython-311) para que varias versiones de Python puedan coexistir sin conflictos.

Esto es especialmente importante cuando se utilizan:

  • Entornos virtuales
  • Python del sistema + Python específico de un entorno
  • Herramientas como pyenv, conda o imágenes de Docker

¿Dónde se encuentra la carpeta pycache?

La carpeta __pycache__ aparece en el mismo directorio que el módulo de Python que se está ejecutando.

Estructura de ejemplo:


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

Si importas un módulo desde otro directorio, ese directorio también generará su propia carpeta __pycache__.

En entornos virtuales

Los entornos virtuales suelen contener muchas carpetas __pycache__ dentro de los paquetes instalados. Esto es normal: las importaciones de paquetes generan archivos .pyc en su primer uso.

¿Cómo acelera pycache los scripts de Python?

Ejecutar un script de Python normalmente requiere:

  1. Analizar el texto
  2. Construir un Abstract Syntax Tree (AST)
  3. Compilar el AST a bytecode
  4. Ejecutar el bytecode

Los pasos 1–3 se omiten cuando Python encuentra un archivo .pyc actualizado. Por eso:

  • La primera ejecución puede ser ligeramente más lenta
  • Las ejecuciones posteriores son más rápidas (especialmente en bases de código grandes)

Archivos pyc basados en hash (PEP 552)

Las versiones modernas de Python admiten:

  • Archivos .pyc basados en marca de tiempo (por defecto)
  • Archivos .pyc basados en hash (para builds reproducibles, empaquetado, imágenes de Docker)

Esto hace que la generación de bytecode sea más estable en entornos automatizados o contenerizados.

¿Puedo eliminar la carpeta pycache?

Sí, eliminar __pycache__ es seguro.

Python la recreará automáticamente la próxima vez que ejecutes tus scripts. El único inconveniente: la siguiente ejecución puede ser ligeramente más lenta debido a la recompilación.

Para eliminar todas las carpetas __pycache__ de forma recursiva:

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

Casos de uso comunes para eliminar pycache

  • Depurar problemas de importación
  • Después de renombrar o reubicar módulos
  • Al empaquetar para despliegue
  • Para reducir “ruido” antes de un commit de Git o una build de Docker

¿Cómo desactivo la creación de archivos pycache?

Puedes desactivar la creación de archivos .pyc configurando la variable de entorno:

export PYTHONDONTWRITEBYTECODE=1

Cuando está activada:

  • Python no generará archivos .pyc
  • No se crearán carpetas __pycache__

Esto se usa habitualmente en:

  • Imágenes de Docker (para reducir el tamaño de las capas)
  • Pipelines de CI
  • Scripts pequeños donde el rendimiento no es relevante

Para hacer que esta configuración sea permanente, añade la variable a la configuración de tu shell (por ejemplo, ~/.bashrc).

Cómo ignorar archivos pycache en Git

Dado que los archivos .pyc son específicos de máquina y se generan automáticamente, no deberían almacenarse en control de versiones.

Añade esto a tu .gitignore:

__pycache__/
*.pyc

La regla *.pyc es opcional pero útil cuando versiones antiguas de Python colocan los .pyc junto al .py.

¿Qué ocurre si elimino la carpeta pycache?

No se rompe nada. Tu script seguirá ejecutándose con normalidad.

Python simplemente:

  1. Detectará que falta el archivo .pyc
  2. Recompilará el archivo .py
  3. Recreará el directorio __pycache__ y el archivo .pyc

Solo la primera ejecución después de la eliminación será ligeramente más lenta.

FAQ

1. ¿Cuál es el propósito de la carpeta __pycache__ en Python?

La carpeta almacena archivos de bytecode .pyc, que permiten que Python arranque más rápido en ejecuciones posteriores.

2. ¿Puedo eliminar la carpeta __pycache__?

Sí. Eliminarla es seguro. Python la vuelve a generar automáticamente.

3. ¿Cómo puedo ignorar los archivos __pycache__ en Git?

Añade esto a tu .gitignore:

__pycache__/
*.pyc