Python / Compilar código e criar arquivos EXE

Para distribuir código Python como um EXE do Windows, o PyInstaller pode reunir o programa, o ambiente de execução Python e as bibliotecas necessárias. Um .pyc criado por py_compile contém bytecode de Python, não um executável independente do Windows. Verifique primeiro o pacote em pasta e depois passe ao arquivo único, se necessário, para facilitar o diagnóstico.

Compilação de bytecode e empacotamento de EXE

py_compile transforma o código-fonte em arquivos de bytecode. O PyInstaller coleta interpretador e dependências em uma aplicação distribuível. Isso difere de traduzir um programa Python comum, por meio de C, em código de máquina nativo otimizado. Empacotar não acelera automaticamente a execução nem esconde o conteúdo do código com segurança.

O resultado depende do sistema operacional e da arquitetura. Construa EXEs do Windows no Windows; o PyInstaller não é um compilador cruzado que os gera no Linux com uma opção. Verifique os ambientes compatíveis e a compatibilidade dos pacotes.

Preparar a pasta e o ambiente virtual no Windows

Use o PowerShell no Windows com Python 3 e pip instalados. Abra o terminal em uma pasta de trabalho nova e execute os comandos em ordem. Se py -3 não estiver disponível, substitua-o na primeira linha pelo caminho do Python instalado ou por um comando python que aponte para esse interpretador.

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install "pyinstaller==6.22.3"
.\.venv\Scripts\python.exe -m PyInstaller --version

.venv é o ambiente virtual do projeto. Os comandos seguintes chamam seu Python diretamente; não é preciso ativar scripts nem alterar a política de execução do PowerShell. O exemplo fixa PyInstaller 6.22.3. Ao escolher outra versão, confira novamente compatibilidade e opções. Verifique que a instalação terminou sem erro e que o último comando mostra 6.22.3.

Instale as dependências efetivamente usadas pela aplicação nesse mesmo ambiente. Construir a partir de um Python global cheio de pacotes não utilizados pode complicar a análise e a gestão do resultado.

Salvar um exemplo completo e gerar bytecode

Crie hello.py em UTF-8 na pasta de trabalho:

print("Hello, packaging!")

Hello, packaging!

Execute primeiro o código-fonte; ele deve mostrar a mensagem acima.

.\.venv\Scripts\python.exe hello.py

Para testar somente a compilação de bytecode:

.\.venv\Scripts\python.exe -m py_compile hello.py

Em caso de sucesso, normalmente sem saída, aparece um arquivo como hello.cpython-312.pyc em __pycache__. A marca de versão depende do Python. Renomeá-lo para EXE não o torna independente: o bytecode ainda precisa de um ambiente Python compatível.

Construir e distribuir um pacote em pasta

Execute estes comandos na pasta de trabalho, o segundo apenas depois de a construção terminar com sucesso.

.\.venv\Scripts\python.exe -m PyInstaller --onedir --name hello-folder hello.py
.\dist\hello-folder\hello-folder.exe

A saída é Hello, packaging!. Distribua toda a pasta dist\hello-folder, incluindo EXE e arquivos de suporte. Copiar apenas o executável pode deixar bibliotecas necessárias para trás. Os arquivos auxiliares podem ficar em _internal; a estrutura exata depende dos pacotes e opções.

build guarda arquivos intermediários e de diagnóstico; hello-folder.spec registra a configuração. O usuário recebe o resultado de dist, não suas pastas build ou .venv. Consulte os detalhes na referência de uso do PyInstaller.

Criar um único EXE

Depois que o formato em pasta funcionar, empacote o mesmo código em um único arquivo. Um nome diferente preserva os dois resultados para comparação.

.\.venv\Scripts\python.exe -m PyInstaller --onefile --name hello-single hello.py
.\dist\hello-single.exe

dist\hello-single.exe pode ser distribuído sozinho e mantém a mesma saída. Ao iniciar, extrai arquivos internos para um local temporário, o que pode aumentar o tempo de abertura. Compare tamanho e velocidade na aplicação real, sem presumir vantagens garantidas.

Não acrescente --windowed a este exemplo de console. A opção pode servir para interfaces gráficas sem console, mas aplicá-la indiscriminadamente a programas com print() ou input() dificulta entrada, saída e diagnóstico. Investigue a causa em vez de adotar execução como administrador ou desativação de proteções como soluções padrão.

Os exemplos de pasta e arquivo único foram construídos no Windows com Python 3.12.14 e PyInstaller 6.22.3, e suas saídas foram verificadas. São testes de console no mesmo computador, não em outro PC sem Python nem em uma aplicação gráfica.

Incluir textos, imagens e outros dados

Não presuma que todos os arquivos lidos pelo código sejam coletados automaticamente. Salve message.txt em UTF-8 com a linha Hello from bundled data!. Crie ao lado hello_data.py com este código completo:

from pathlib import Path

message = Path(__file__).resolve().with_name("message.txt")
print(message.read_text(encoding="utf-8").strip())

Hello from bundled data!

O código-fonte e o pacote seguinte devem mostrar a mesma mensagem. Um caminho baseado em __file__ não depende da pasta atual do terminal e pode localizar arquivos dentro do pacote.

.\.venv\Scripts\python.exe -m PyInstaller --onefile --name hello-data --add-data "message.txt:." hello_data.py
.\dist\hello-data.exe

--add-data "message.txt:." inclui o arquivo no nível superior do pacote. O separador documentado atualmente é dois-pontos; não misture exemplos antigos específicos de plataforma. Faça os caminhos coincidirem com as regras de inclusão de dados para imagens e configurações. Alterações em dados extraídos de um EXE único não são armazenamento persistente. Salve configurações e resultados do usuário em outro local gravável.

Diagnosticar falhas e conferir a distribuição

1. Se o EXE fechar imediatamente, execute-o no PowerShell em vez de dar duplo clique para ler o erro. Primeiro confirme que o código-fonte funciona no mesmo ambiente virtual.
2. Para módulos ausentes, examine a instalação e o método de importação. Imports dinâmicos podem exigir configurações adicionais. Leia build\nome\warn-nome.txt, reconhecendo que nem todo aviso é fatal.
3. Para dados ausentes, compare o destino de --add-data com o caminho no código. Volte ao formato em pasta para inspecionar os arquivos e reduzir as possibilidades.
4. Teste as funções no sistema e arquitetura de destino. Inclua um ambiente separado sem Python, acesso a arquivos, dependências de programas externos e condições de redistribuição dos pacotes.

Consulte o guia de solução de problemas do PyInstaller. Separe construção de execução e registre código reproduzível, versões dos pacotes e mensagens de erro para facilitar o diagnóstico.