Skip to content
BranchesTags

Repository files navigation

GenPyEXE

PyPI Python Licença MIT CI

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

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.

Opção Efeito no Windows
(sempre) Entrada em Aplicativos e Recursos, com desinstalador
desktop_shortcut Oferece atalho na Área de Trabalho
start_menu Entrada no Menu Iniciar + atalho de desinstalação
per_user_install Instala sem pedir senha de administrador (sem UAC)
add_to_path Acrescenta a pasta ao PATH — e a remove ao desinstalar
file_associations Duplo clique em .suaext abre o seu aplicativo
run_at_startup Inicia junto com o Windows
launch_after_install Executa ao terminar a instalação
keep_data_on_uninstall Preserva logs e configurações na desinstalação

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.

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,
    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 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

Documento Conteúdo
docs/instalacao.md Instalação, Inno Setup, requisitos
docs/uso-gui.md Assistente gráfico, etapa por etapa
docs/uso-cli.md Todos os comandos e opções
docs/api.md Referência da biblioteca
docs/instalador-windows.md Como cada opção age no Windows
docs/receitas-bibliotecas.md Bibliotecas cobertas e limitações
docs/solucao-de-problemas.md Erros comuns e como resolver

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 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.

About

Transforma uma pasta de projeto Python num executavel Windows portatil e num instalador 64 bits.

github.com/DaviKdS/GenPyEXE

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages