Instalador do Windows para um app Python (PyInstaller para Setup.exe)

O PyInstaller transforma um programa Python em um .exe do Windows que roda sem o Python instalado. O que ele não faz é instalar esse programa: nada no menu Iniciar, nenhum desinstalador, nada nas Configurações do Windows. Para isso, você empacota a saída do PyInstaller em um instalador. Aqui está o caminho completo, do script ao Setup.exe.

Passo 1: congelar o app com o PyInstaller

Instale o PyInstaller no ambiente do projeto e compile a partir da pasta que contém o seu script de entrada:

pip install pyinstaller
pyinstaller --noconsole --onedir --name MyApp --icon app.ico main.py

O que cada opção faz:

• --onedir (o padrão) gera uma pasta dist/MyApp/ com MyApp.exe e uma pasta _internal/ com as bibliotecas. Use esta opção para instaladores. Ela inicia mais rápido que --onefile, porque nada precisa ser descompactado em uma pasta temporária a cada execução, e chama menos a atenção das heurísticas de antivírus.
• --noconsole esconde a janela preta do console em apps gráficos (Tkinter, PyQt, Kivy e similares). Deixe de fora em ferramentas de linha de comando.
• --icon app.ico incorpora o ícone no .exe. Mantenha o mesmo .ico para o instalador.
• --name MyApp dá nome ao executável e à pasta de saída.

Arquivos de dados que o seu programa abre em tempo de execução (imagens, templates de configuração, modelos) precisam ser adicionados com --add-data "src;dest" ou no arquivo .spec; caso contrário, não estarão em dist/MyApp/.

Abra dist/MyApp/MyApp.exe e confira se o app roda. Se puder, copie a pasta dist/MyApp inteira para outro PC com Windows sem Python e execute lá também.

Passo 2: compactar a pasta de saída

Compacte em zip o conteúdo de dist/MyApp/: MyApp.exe e _internal/. Não inclua build/, o arquivo .spec nem a sua árvore de código-fonte. O zip é o que será instalado, byte a byte.

Passo 3: gerar o instalador

1. Envie o zip para o ExeTup. Ele detecta MyApp.exe como programa principal.
2. Informe o nome do app, a versão, o editor e, se quiser, uma licença.
3. Escolha todos os usuários (Program Files, pedido de administrador) ou usuário atual (sem direitos de administrador). Ferramentas distribuídas a colegas costumam funcionar melhor por usuário.
4. Escolha a arquitetura. O PyInstaller compila para o Python com o qual você o executou, então um Python de 64 bits gera um app de 64 bits.
5. Envie o app.ico, ative os atalhos que quiser e gere o instalador.
6. Baixe o Setup.exe e teste no Windows.

Observações específicas do Python

• Falsos positivos de antivírus. Pacotes do PyInstaller são alvo frequente de heurísticas de antivírus excessivamente cautelosas, principalmente builds --onefile. Um build onedir dentro de um instalador comum, colocado em Program Files, se comporta como qualquer outro programa e tem menos chance de ser sinalizado. A assinatura de código ajuda ainda mais.
• Tamanho. Um app Tkinter tem de 20 a 40 MB; PyQt, NumPy ou PyTorch elevam isso bem mais. A compressão LZMA do instalador normalmente reduz pela metade. Exclua módulos que você não usa com --exclude-module para manter o pacote enxuto.
• Primeira execução. Como o onedir não precisa descompactar nada, a primeira inicialização é tão rápida quanto as seguintes.
• Atualizações. Distribua um novo instalador com um número de versão maior. Instalar por cima da versão anterior substitui os arquivos no lugar.
• Ferramentas de console. Para um programa de linha de comando, considere uma instalação por máquina e informe aos usuários a pasta de instalação; o instalador não a adiciona ao PATH.

Alternativas

Nuitka e cx_Freeze também produzem uma pasta com um .exe; a etapa do instalador é idêntica. Se você preferir escrever o script do instalador por conta própria, tanto o NSIS quanto o Inno Setup funcionam com a saída do PyInstaller.

Perguntas frequentes

Devo usar --onefile ou --onedir para um instalador?

--onedir. O instalador já entrega aos usuários um único Setup.exe para baixar, então não há motivo para pagar a inicialização lenta e a descompactação em pasta temporária do onefile. Onedir também é o padrão do PyInstaller.

Os usuários precisam ter o Python instalado?

Não. O PyInstaller empacota o interpretador Python e as bibliotecas na pasta, e o instalador coloca essa pasta na máquina do usuário.

Por que o Windows avisa sobre o meu instalador?

Downloads novos e não assinados acionam o Microsoft SmartScreen até ganharem reputação. Veja o guia sobre o SmartScreen para saber o que você pode fazer.

Posso incluir uma configuração de exemplo ou uma pasta de dados?

Sim. Adicione com o --add-data do PyInstaller, para que fique dentro de _internal/, ou inclua na etapa "Outros arquivos" do ExeTup para colocá-la ao lado de MyApp.exe.