pyghidra

3.0.2 verified Sat May 09 auth: no python

pyghidra is a Python package that provides a native CPython interface for Ghidra, the NSA's reverse engineering framework. Current version 3.0.2 supports Ghidra 12.x and requires Python >=3.9. It enables scripting Ghidra with standard Python and accessing its API directly within the Ghidra GUI or headlessly.

pip install pyghidra

Common errors

error ImportError: cannot import name 'start' from 'pyghidra' ↓

cause pyghidra not installed or incompatible version.

fix

Install pyghidra with pip install pyghidra or upgrade to latest.

error ValueError: Ghidra installation directory not set. Set GHIDRA_INSTALL_DIR environment variable. ↓

cause Environment variable GHIDRA_INSTALL_DIR not set or pointing to invalid path.

fix

Set GHIDRA_INSTALL_DIR=/path/to/ghidra before running Python.

error ghidra.program.model.listing.Function is not subscriptable ↓

cause Calling list() or indexing on a function iterator incorrectly.

fix

Iterate directly: for func in funcs: or convert to list with list(funcs).

Warnings

gotcha pyghidra requires a compatible Ghidra installation. Version 3.0.2 works with Ghidra 12.x; older versions (e.g., 2.x) are for Ghidra 11.x. Mixing versions causes import errors. ↓

fix Ensure GHIDRA_INSTALL_DIR environment variable points to the correct Ghidra version matching pyghidra.

deprecated The `pyghidra.open()` function is deprecated in 3.0.0 and removed in later versions. Use `pyghidra.start()` as a context manager. ↓

fix Replace `pyghidra.open()` with `pyghidra.start()`.

gotcha Ghidra API classes are accessed with Python-style imports but follow Java package paths. Common mistake: using camelCase instead of PEP8 import style. ↓

fix Use full Java package path: e.g., `from ghidra.program.model.listing import Function`.

Imports

pyghidra
```
import pyghidra
```
Direct import works; no submodule needed.
start
wrong
```
from pyghidra import start
```
correct
```
pyghidra.start()
```
start is a top-level function in pyghidra module; direct import works but calling pyghidra.start() is clearer.
Ghidra API
wrong
```
import ghidra.program.model.listing
```
correct
```
from ghidra.program.model.listing import Function as GhidraFunction
```
Ghidra API classes must be imported via full Java package path; pyghidra makes them accessible as Python modules.

Quickstart

Start Ghidra headlessly, load a binary, and iterate over its functions.

import pyghidra
import os

def analyze_binary():
    binary_path = os.environ.get('BINARY_PATH', '/bin/ls')
    with pyghidra.start(binary_path) as ctx:
        program = ctx.getCurrentProgram()
        print(f"Analyzing: {program.getName()}")
        funcs = program.getFunctionManager().getFunctions(True)
        for func in funcs:
            print(func.getName())

if __name__ == '__main__':
    analyze_binary()