GenPyEXE

Transforme uma pasta de projeto Python num executável Windows com instalador.

Você aponta para a pasta. O GenPyEXE descobre o arquivo inicial, as dependências e os recursos, converte a sua imagem em ícone, grava os metadados do Windows, compila num ambiente isolado e entrega dois artefatos: um .exe portátil e um instalador 64 bits que registra o aplicativo no Windows.

import genpyexeks

resultado = genpyexeks.build(
    "C:/projetos/MeuApp",
    app_name="Meu App",
    version="1.0.0",
    publisher="Seu Nome",
    icon="assets/logo.png",
    installer=True,
)

print(resultado.exe_path)        # dist/Meu App.exe
print(resultado.installer_path)  # dist/meu-app-1.0.0-setup-x64.exe

Índice

• Por que existe
• Instalação
• Três formas de usar
• O que o instalador faz
• Suporte a bibliotecas
• Recursos dentro do executável
• Ambiente isolado
• Perfil do projeto
• Referência da API
• Referência da CLI
• Documentação completa
• Requisitos
• Segurança e privacidade
• Licença e autoria

Por que existe

Empacotar um projeto Python para Windows costuma virar um ritual manual: descobrir os --hidden-import, lembrar de copiar a pasta assets/, gerar o .ico em sete resoluções, escrever o VERSIONINFO na mão e — se quiser que o aplicativo apareça em Aplicativos e Recursos — aprender a sintaxe do Inno Setup.

O GenPyEXE faz esse caminho inteiro uma vez e o deixa repetível.

Instalação

pip install genpyexe          # núcleo: API + CLI
pip install "genpyexe[gui]"   # com o assistente gráfico

Ou baixe os binários prontos em Releases: um executável portátil e um instalador 64 bits, sem precisar de Python instalado.

Instala como genpyexe, importa como genpyexeks. Nome de distribuição diferente do nome de importação é comum em Python (pillow → PIL, beautifulsoup4 → bs4). O nome de instalação acompanha o produto; o pacote importável mantém genpyexeks.

O pip normaliza o nome antes de procurá-lo (PEP 503), então genpyexe e GenPyEXE levam ao mesmo pacote.

Para a versão em desenvolvimento, direto do repositório:

pip install "git+https://github.com/DaviKdS/GenPyEXE.git"

Confira o ambiente antes do primeiro build:

genpyexe doctor

Três formas de usar

1. Assistente gráfico

genpyexe gui

Quatro etapas: arraste a pasta, confira o que foi detectado, marque as integrações desejadas e acompanhe o log ao vivo.

┌─ GenPyEXE ─────────────────────────────────────────┐
│ 1. Projeto  2. Aplicativo  3. Instalador  4. Build │
├────────────────────────────────────────────────────┤
│   ╔══════════════════════════════════════════╗     │
│   ║     Arraste a pasta do projeto aqui      ║     │
│   ║        ou use o botão Procurar           ║     │
│   ╚══════════════════════════════════════════╝     │
│                                                    │
│   Detectado automaticamente                        │
│     Arquivo inicial: main.py                       │
│     Dependências:    3 - PySide6, pandas, requests │
│     Recursos:        assets/, templates/           │
│     Tipo de app:     gráfico (sem console)         │
└────────────────────────────────────────────────────┘

2. Linha de comando

genpyexe build ./MeuProjeto \
    --name "Meu App" \
    --version 1.0.0 \
    --publisher "Seu Nome" \
    --icon assets/logo.png \
    --onefile --windowed \
    --installer --desktop-shortcut --start-menu

3. Biblioteca Python

import genpyexeks
from genpyexeks import InstallerOptions

genpyexeks.build(
    "./MeuApp",
    app_name="Meu App",
    installer=InstallerOptions(
        desktop_shortcut=True,
        start_menu=True,
        add_to_path=False,
        file_associations=[".meuext"],
        run_at_startup=False,
        per_user_install=True,
    ),
)

O que o instalador faz

Cada item é opcional e independente — marque só o que o seu aplicativo precisa.

O instalador usa um AppId determinístico derivado de publicador + nome do app. Na prática: instalar a versão 2.0 substitui a 1.0 em Aplicativos e Recursos, em vez de criar uma segunda entrada duplicada.

Suporte a bibliotecas

O PyInstaller já cobre a maior parte do ecossistema através dos seus hooks e do pyinstaller-hooks-contrib. O GenPyEXE acrescenta uma camada de receitas para os casos em que a coleta automática costuma deixar arquivos para trás:

• Interfaces gráficas — PySide6, PyQt5/6, CustomTkinter, tkinterdnd2, ttkbootstrap, Kivy, pygame, Flet
• Documentos — python-docx, reportlab, fpdf2, pdfplumber, PyMuPDF, openpyxl
• Dados e IA — pandas, numpy, scipy, scikit-learn, PyTorch, transformers, EasyOCR
• Web — Flask, FastAPI, Uvicorn, Selenium, Playwright
• Sistema — pywin32, comtypes, pyautogui, SQLAlchemy

Bibliotecas fora dessa lista seguem o comportamento padrão do PyInstaller — a ausência de receita nunca quebra um build.

Quando um pacote depende de algo que nenhuma opção de empacotamento resolve — o binário do Tesseract, os navegadores do Playwright, modelos baixados na primeira execução — o GenPyEXE emite um aviso explícito em vez de gerar um executável que falharia na máquina do usuário final.

Para ver o que é aplicado ao seu projeto — ou desligar a camada automática:

genpyexe recipes                  # lista as receitas
genpyexe build ./MeuApp --no-recipes

Recursos dentro do executável

O GenPyEXE empacota assets/, templates/ e afins automaticamente. Mas empacotar não basta: dentro do .exe o PyInstaller descompacta os dados numa pasta temporária, e o caminho relativo do seu código quebra.

genpyexe helper ./MeuApp     # cria resources.py no projeto

from resources import resource_path, user_data_dir

logo = resource_path("assets", "logo.png")   # leitura: funciona empacotado ou não
log = user_data_dir() / "app.log"            # escrita: pasta persistente do usuário

As duas são separadas de propósito: em --onefile, a pasta de resource_path() é temporária e some quando o aplicativo fecha. O que o app precisa gravar vai em user_data_dir() — a mesma pasta que a opção keep_data_on_uninstall do instalador preserva.

O arquivo gerado usa apenas a biblioteca padrão: não cria dependência do seu aplicativo com o GenPyEXE nem aumenta o executável.

Ambiente isolado

Por padrão, o GenPyEXE cria uma venv contendo apenas as dependências declaradas do projeto e roda o PyInstaller lá dentro.

O motivo é concreto: um ambiente Python de uso geral acumula bibliotecas pesadas. Numa máquina com torch, opencv e easyocr instalados, o site-packages passa de 1,6 GB — e qualquer erro para mais na análise estática custa centenas de megabytes no executável final.

O ambiente é cacheado pelo hash das dependências, então o segundo build é rápido.

genpyexe build ./MeuApp                   # isolado (padrão)
genpyexe build ./MeuApp --no-isolation    # interpretador atual: rápido, offline, exe maior
genpyexe clean                            # remove as venvs em cache

Use --no-isolation quando estiver sem internet ou quando o projeto usar bibliotecas que só existem localmente.

Perfil do projeto

Grave as escolhas em genpyexe.toml e reconstrua com um comando:

genpyexe init ./MeuApp     # cria o perfil interativamente
genpyexe build ./MeuApp    # lê o perfil automaticamente

[app]
name = "Meu App"
version = "1.0.0"
publisher = "Seu Nome"
icon = "assets/logo.png"
entrypoint = "main.py"

[build]
mode = "onefile"       # onefile | onedir
console = "windowed"   # windowed | console
isolated = true

[installer]
enabled = true
desktop_shortcut = true
start_menu = true
per_user_install = true
add_to_path = false
file_associations = [".meuext"]

Referência da API

genpyexeks.build(
    project_dir,              # pasta do projeto
    app_name=None,            # padrão: nome da pasta
    version="1.0.0",
    publisher="",
    description="",
    copyright="",             # derivado do publisher, se vazio
    url="",
    icon=None,                # .ico, .png, .jpg, .bmp, .webp
    auto_icon=False,          # gera ícone com as iniciais
    entrypoint=None,          # detectado se omitido
    onefile=True,
    windowed=True,
    isolated=True,
    base_python=None,
    installer=False,          # True ou InstallerOptions(...)
    output_dir=None,
    hidden_imports=None,
    extra_data=None,          # [(origem, destino), ...]
    collect_all=None,
    excludes=None,
    apply_recipes=True,      # receitas automáticas por biblioteca
    uac_admin=False,
    clean=False,
    on_progress=None,         # callback(etapa, mensagem, percentual)
    on_output=None,           # callback(linha)
) -> BuildResult

BuildResult traz exe_path, installer_path, iss_path, spec_path, icon_path, notices_path, exe_size_mb, duration_seconds, warnings e messages.

Analisar sem construir:

info = genpyexeks.analyze("./MeuApp")
print(info.entrypoint_rel, info.requirements, info.suggests_windowed)

Referência da CLI

genpyexe doctor                 Diagnostica Python, PyInstaller e Inno Setup
genpyexe init <pasta>           Cria o perfil genpyexe.toml interativamente
genpyexe build <pasta>          Gera o executável (e o instalador)
genpyexe icon <imagem>          Converte uma imagem em .ico multi-resolução
genpyexe icon -g "Meu App"      Gera um ícone com as iniciais
genpyexe helper <pasta>         Gera o módulo de acesso a recursos no projeto
genpyexe recipes                Lista as receitas de empacotamento por biblioteca
genpyexe clean                  Remove as venvs de build em cache
genpyexe gui                    Abre o assistente gráfico

genpyexe build --help lista todas as opções.

Documentação completa

Requisitos

• Windows de 64 bits (o alvo dos artefatos é o Windows)
• Python 3.9 ou superior, 64 bits
• Inno Setup 6 — apenas para compilar o instalador. Sem ele, o .exe portátil é gerado normalmente e o script .iss fica pronto, junto de um guia de compilação.

O GenPyEXE nunca instala nada automaticamente. Quando falta uma ferramenta, ele informa o comando exato e a decisão fica com você.

Segurança e privacidade

• Nenhuma credencial, token ou dado pessoal no código. Variáveis opcionais documentadas em .env.example.
• Todo subprocesso é executado com lista de argumentos e shell=False — sem interpolação de string em linha de comando.
• A análise do projeto usa apenas a AST: o seu código nunca é importado nem executado durante a detecção.
• Os logs registram caminhos e versões, nunca conteúdo de arquivos ou variáveis de ambiente.

Sobre o SmartScreen: executáveis não assinados disparam um aviso do Windows na primeira execução. Isso é comportamento normal do sistema, não um defeito do GenPyEXE, e só desaparece com um certificado de assinatura de código. O GenPyEXE suporta signtool opcionalmente, mas o certificado é seu e nunca deve ir para o repositório.

Licença e autoria

MIT — veja LICENSE.

Copyright © 2026 Davi Kasmirski dos Santos — autor e único detentor dos direitos autorais deste projeto.

O que o GenPyEXE gera é seu

Os arquivos que a ferramenta grava no seu projeto — resources.py, o .spec, o .iss, o genpyexe.toml, o THIRD_PARTY_NOTICES.txt, os ícones e os executáveis — não estão sujeitos à cláusula de atribuição da MIT. Use-os, modifique-os e distribua-os sob qualquer licença, comercial ou não, sem precisar citar o GenPyEXE.

Veja LICENSE-EXCECAO-DE-SAIDA.md. É o mesmo mecanismo da exceção de bootloader do PyInstaller.

A exceção alcança apenas a saída gerada: o código-fonte do próprio genpyexeks continua sob a MIT integral. O que você gera é seu; a ferramenta que gera continua sendo MIT.

O GenPyEXE gera automaticamente um arquivo THIRD_PARTY_NOTICES.txt ao lado do executável, com as licenças das bibliotecas empacotadas. Isso cumpre as cláusulas de atribuição dessas licenças e não divide a autoria do seu aplicativo nem deste projeto.

Ferramentas de terceiros utilizadas — nenhuma redistribuída aqui:

• PyInstaller (GPLv2 com exceção de bootloader) — invocado como programa externo. A exceção autoriza expressamente distribuir sob qualquer licença os executáveis gerados por ele.
• Inno Setup (JR Software) — gratuito inclusive para uso comercial. O GenPyEXE gera o script .iss e chama o compilador ISCC.exe.
• Pillow, Jinja2, Typer, Rich, PySide6 — dependências declaradas em pyproject.toml, cada uma sob a própria licença.