Um executável é um arquivo que roda sem instalar Python. Ele contém seu código, o interpretador e as bibliotecas. Primeiramente, isso é útil para usuários finais não técnicos. Por exemplo, entregar uma ferramenta para um cliente leigo. Além disso, executáveis evitam vazamento do código-fonte. A voz passiva é usada aqui: “o programa é empacotado como um .exe”. Quando utilizar essa abordagem? Em aplicações desktop ou scripts internos. Também é comum em ambientes corporativos com Python bloqueado. Existem várias ferramentas: PyInstaller, cx_Freeze, Nuitka e Py2exe. Cada uma tem prós e contras em tamanho e compatibilidade. Neste guia, focaremos no PyInstaller (mais popular). Ele funciona no Windows, Linux e macOS de forma similar. Vamos entender os conceitos e exemplos práticos.
PyInstaller: a ferramenta mais completa
PyInstaller analisa seu script e coleta todas as dependências.
Ele empacota tudo em uma única pasta ou um único arquivo.
Primeiro, instale com pip install pyinstaller.
Depois, execute: pyinstaller meu_script.py.
Isso gera uma pasta dist/meu_script/ com o executável.
Para criar um único arquivo, use a flag --onefile.
Por exemplo: pyinstaller --onefile meu_script.py.
O resultado será um .exe (Windows) ou binário (Linux).
Esse arquivo pode ser copiado e executado em qualquer máquina similar.
Foi observado que o modo --onefile é mais lento para iniciar.
Isso ocorre porque ele extrai os arquivos para uma pasta temporária.
Portanto, prefira o modo pasta para aplicações grandes.
Além disso, ícones personalizados são adicionados com --icon=meu_icone.ico.
Veja um exemplo completo:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
# meu_script.py - um programa simples import sys from datetime import datetime def main(): print("=== Gerador de Saudação ===") nome = input("Digite seu nome: ") hora = datetime.now().hour if hora < 12: saudacao = "Bom dia" elif hora < 18: saudacao = "Boa tarde" else: saudacao = "Boa noite" print(f"{saudacao}, {nome}!") input("Pressione Enter para sair...") if __name__ == "__main__": main() |
Para transformar esse script em executável:
pyinstaller --onefile --name Saudador meu_script.py
O arquivo Saudador.exe aparecerá na pasta dist/.
Esse executável roda em qualquer Windows sem Python instalado.
A voz passiva é aplicada: “as dependências são detectadas automaticamente”.
Isso inclui bibliotecas como datetime (built-in).
Quando usar cada modo e ferramenta
O modo --onefile é ideal para distribuição simples.
Por exemplo, enviar por e-mail ou disponibilizar em um site.
O modo pasta é melhor para aplicações grandes com muitos assets.
Assim, cada arquivo pode ser atualizado separadamente.
Outra ferramenta é o cx_Freeze, mais leve que o PyInstaller.
Ele é ótimo para scripts de linha de comando simples.
Já o Nuitka compila Python para C, gerando executáveis muito rápidos.
Contudo, o tempo de compilação é bem maior.
Quando evitar executáveis? Em projetos com muitas dependências dinâmicas.
Por exemplo, pacotes que carregam plugins via importlib.
O PyInstaller pode não detectar essas importações ocultas.
Nesse caso, use o hook manual ou o modo --hidden-import.
Foi observado que antivírus falsamente detectam executáveis PyInstaller.
Isso acontece devido à técnica de empacotamento (bytecode).
Portanto, assine digitalmente seu executável para maior confiança.
Dicas práticas e resolução de problemas
Teste seu executável em uma máquina limpa (sem Python).
Use --debug para ver logs detalhados de erro.
Muitos problemas surgem por caminhos de arquivos incorretos.
No código, use sys._MEIPASS para acessar arquivos extras.
Isso funciona apenas no PyInstaller.
Exemplo de acesso a um arquivo de configuração:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
import sys import os def resource_path(relative_path): """Retorna o caminho correto para arquivos extras.""" try: base_path = sys._MEIPASS except AttributeError: base_path = os.path.abspath(".") return os.path.join(base_path, relative_path) # Uso caminho_config = resource_path("config.json") |
Inclua arquivos adicionais com --add-data "config.json;." (Windows).
No Linux ou macOS, use dois pontos: --add-data "config.json:.".
Outra dica: reduza o tamanho do executável com --exclude-module.
Exclua bibliotecas grandes e não utilizadas (ex: matplotlib, pandas).
A fórmula para estimar o tempo de inicialização é complexa:
\(T_{\text{inicial}} \approx T_{\text{extração}} + T_{\text{importação}}\).
Por fim, lembre-se: executáveis não são código-fonte seguro.
Um engenheiro reverso pode extrair seu .pyc com ferramentas.
Portanto, use ofuscação adicional para proteção comercial.
Mas para a maioria dos casos, o PyInstaller é mais que suficiente.
Comece hoje mesmo transformando seus scripts em aplicações standalone!