Cómo crear un ejecutable de Python con PyInstaller

PyInstaller empaqueta una aplicación de Python junto con el intérprete y las dependencias necesarias para ejecutarla en una computadora que no tenga Python instalado. Es una opción práctica para distribuir herramientas de escritorio, utilidades internas y scripts a usuarios no técnicos. No convierte el programa en código nativo puro ni garantiza compatibilidad entre todos los sistemas: debes construir y probar el ejecutable en cada plataforma objetivo.

Esta guía muestra un flujo confiable desde un entorno virtual limpio hasta la distribución. Antes de empaquetar, revisa cómo crear entornos virtuales con venv; un entorno aislado evita incluir bibliotecas innecesarias.

Preparar un proyecto sencillo

Crea una carpeta con el archivo principal:

mi_aplicacion/
├── app.py
└── recursos/
    └── mensaje.txt

Contenido de app.py:

from pathlib import Path

def main() -> None:
    ruta = Path(__file__).parent / "recursos" / "mensaje.txt"
    print(ruta.read_text(encoding="utf-8"))
    input("Pulsa Enter para salir...")

if __name__ == "__main__":
    main()

Organizar rutas con pathlib reduce errores, aunque los recursos empaquetados requieren una consideración adicional que veremos después.

Crear y activar el entorno

python -m venv .venv

En PowerShell:

.venv\Scripts\Activate.ps1

En macOS o Linux:

source .venv/bin/activate

Instala PyInstaller dentro del entorno:

python -m pip install --upgrade pip
python -m pip install pyinstaller

Utilizar python -m pip ayuda a asegurar que instalas en el mismo intérprete activo. Si aparece un problema de imports, consulta cómo corregir ModuleNotFoundError.

Crear la primera compilación

pyinstaller app.py

PyInstaller crea normalmente:

build/
dist/
app.spec

Dentro de dist/app/ encontrarás el ejecutable y sus dependencias. El modo de carpeta facilita el diagnóstico porque los archivos están visibles. Pruébalo antes de pasar a un único archivo.

Generar un solo archivo

pyinstaller --onefile app.py

El ejecutable único extrae componentes en una carpeta temporal al iniciarse. Por eso puede tardar más en abrir y algunas herramientas de seguridad pueden analizarlo con mayor intensidad. El modo de carpeta no es inferior; en aplicaciones grandes puede ser más rápido y sencillo de actualizar.

Ocultar la consola en aplicaciones gráficas

Para una interfaz gráfica en Windows o macOS puedes utilizar:

pyinstaller --onefile --windowed app.py

--windowed o --noconsole evita mostrar la terminal. No lo uses mientras depuras: sin consola puedes perder mensajes importantes. Implementa registros en archivo antes de ocultarla.

Añadir un icono

pyinstaller --onefile --icon=icono.ico app.py

Windows utiliza habitualmente .ico; macOS utiliza .icns. Un archivo de imagen cualquiera renombrado no se convierte automáticamente en un icono válido.

Incluir archivos de datos

El separador de --add-data puede variar según la versión y la plataforma. Una forma común es:

pyinstaller --onefile --add-data "recursos:recursos" app.py

En configuraciones antiguas de Windows se utilizaba punto y coma:

pyinstaller --onefile --add-data "recursos;recursos" app.py

Consulta la documentación oficial de uso de PyInstaller para la sintaxis de tu versión.

Encontrar recursos en el ejecutable

En versiones modernas, __file__ suele funcionar de forma consistente dentro del bundle. Una función sencilla es:

from pathlib import Path

def recurso(relativa: str) -> Path:
    return Path(__file__).resolve().parent / relativa

Después:

ruta = recurso("recursos/mensaje.txt")

No escribas datos modificables dentro de la carpeta temporal de un ejecutable onefile. Guarda configuraciones y documentos del usuario en una ubicación persistente apropiada.

Imports ocultos

PyInstaller analiza imports, pero algunas bibliotecas cargan módulos dinámicamente. Si falta uno:

pyinstaller --onefile --hidden-import=paquete.modulo app.py

Antes de añadir opciones al azar, ejecuta el programa desde el entorno y revisa el registro de compilación. Algunas bibliotecas disponen de hooks oficiales o comunitarios.

Utilizar el archivo .spec

El archivo app.spec representa la configuración de construcción. Es útil cuando incluyes varios recursos, hooks, metadatos o ejecutables.

pyinstaller app.spec

Guarda el archivo spec en el control de versiones cuando sea parte del proceso reproducible. La documentación sobre el modo de funcionamiento de PyInstaller explica cómo recopila módulos y cómo se inicia el bundle.

Limpiar compilaciones anteriores

pyinstaller --clean --noconfirm --onefile app.py

--clean elimina cachés temporales de construcción y --noconfirm reemplaza la salida existente. Úsalos en automatización, pero conserva registros cuando investigues un problema.

Reducir el tamaño

Construye desde un entorno que contenga solo las dependencias necesarias. Importar una biblioteca grande puede incorporar muchos componentes. No elimines archivos internos manualmente sin entenderlos. Para proyectos que serán instalados por usuarios técnicos, quizá sea mejor publicar un paquete; la guía para publicar en PyPI presenta esa alternativa.

Seguridad y falsos positivos

Algunos antivirus pueden marcar ejecutables empaquetados porque malware real también utiliza empaquetadores. Firma el binario cuando corresponda, distribúyelo desde un canal confiable, publica hashes y evita compresores agresivos si generan alertas. PyInstaller no cifra ni protege el código de manera fuerte; personas con experiencia pueden inspeccionar componentes.

Probar en una máquina limpia

No basta con abrir el ejecutable en la computadora de desarrollo. Pruébalo en una máquina virtual o equipo sin Python, con rutas que contengan espacios y caracteres especiales. Comprueba permisos, red, archivos de configuración, errores y actualizaciones. Para trabajar desde el editor, la guía de VS Code en Windows ayuda a seleccionar el intérprete correcto.

Comando recomendado para una aplicación de consola

pyinstaller ^
  --clean ^
  --noconfirm ^
  --onefile ^
  --name MiAplicacion ^
  --add-data "recursos;recursos" ^
  app.py

En macOS y Linux sustituye la continuación de línea y verifica el separador de datos según tu versión.

Errores frecuentes

Los problemas habituales son construir en un sistema y esperar que funcione en otro, ocultar la consola antes de depurar, olvidar archivos de datos, usar rutas absolutas del equipo de desarrollo, instalar PyInstaller fuera del entorno correcto y asumir que onefile siempre es mejor. También debes leer las licencias de las dependencias incluidas.

Conclusión

PyInstaller facilita entregar una aplicación Python a usuarios que no desean configurar intérpretes y paquetes. El proceso fiable consiste en partir de un entorno limpio, probar primero el modo de carpeta, incluir recursos de forma explícita, revisar imports dinámicos y validar el resultado en una máquina limpia. El ejecutable es el último paso de un proyecto bien organizado, no una solución para errores que ya existen en el código.