O que é PyGhidra
PyGhidra é a biblioteca oficial para usar a API do Ghidra no CPython 3 nativo. Projetos, programas, símbolos e análises podem fazer parte de fluxos Python reproduzíveis.
Como a API lida diretamente com projetos e programas do Ghidra, fixe o caminho de instalação e o ambiente Python e registre as versões para reproduzir os resultados.
Requisitos e versões
A versão atual é PyGhidra 3.1.0, publicada em 14 de maio de 2026. Ela requer Python 3.9 ou superior, Ghidra 12.0 ou superior e JDK 21.
Se houver várias versões do Ghidra instaladas, confirme explicitamente qual diretório raiz e qual JDK a integração realmente usa.
Como instalar
Crie um ambiente virtual dedicado. Instale pelo PyPI ou use o pacote offline da distribuição oficial. Não use instaladores EXE de terceiros.
Escolha a instalação online ou offline e confirme que python e pip apontam para o mesmo interpretador do ambiente virtual.
- 1
Ambiente virtual
Isole as dependências.
python -m venv .venv - 2
Instalação
Use o interpretador ativo.
python -m pip install --upgrade pyghidra==3.1.0 - 3
Opção offline
Use o pacote oficial incluído.
python -m pip install --no-index -f <GhidraInstallDir>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra
Conectar ao Ghidra
Defina GHIDRA_INSTALL_DIR para a raiz extraída do Ghidra ou passe install_dir para pyghidra.start().
Com várias versões do Ghidra, fixe o caminho e confirme antes de iniciar que o diretório contém as pastas Ghidra e Features.
GHIDRA_INSTALL_DIR=<path-to-ghidra-root>
Primeira automação
Inicie o Ghidra uma vez por processo, abra uma amostra autorizada em um contexto e salve resultados fora da instalação.
Use gerenciadores de contexto como open_program para fechar recursos e mantenha a amostra original separada do projeto gerado.
from pathlib import Path
import pyghidra
with pyghidra.open_program(Path('sample.exe')) as api:
print(api.getCurrentProgram().getName())
Problemas comuns
Verifique Python, java -version, raiz do Ghidra e versões. Trate binários e scripts externos como não confiáveis.
Registre as versões do Python, do pacote e do JDK junto com GHIDRA_INSTALL_DIR para distinguir problemas do ambiente de problemas de compatibilidade da API.
| Sintoma | Causa | Verificação |
|---|---|---|
| Erro de importação | Ambiente incorreto | python -m pip show pyghidra |
| Erro de Java | JDK incorreto | java -version |
| Erro de caminho | Raiz incorreta | GHIDRA_INSTALL_DIR |
| Incompatibilidade da API | Limite de versão | PyGhidra 3.x + Ghidra 12.0+ |
PyGhidra FAQ
PyGhidra está incluído no Ghidra?
PyGhidra é a biblioteca oficial para usar a API do Ghidra no CPython 3 e pode ser instalado pelo pacote oficial ou pelo PyPI.
Qual versão do Python é necessária?
É necessário Python 3.9 ou posterior.
Por que o Ghidra não é encontrado?
Defina GHIDRA_INSTALL_DIR como a raiz extraída do Ghidra ou passe install_dir para pyghidra.start().
Ele substitui o analyzeHeadless?
Não. O PyGhidra controla a API a partir do Python, enquanto o analyzeHeadless é adequado para pipelines de linha de comando. Escolha conforme o fluxo.
O PyGhidra MCP é o mesmo projeto?
Não. As ferramentas MCP são projetos separados e não são o pacote oficial do PyGhidra.