Python client for the libghidra typed RPC layer. Communicates with a running LibGhidraHost extension via binary protobuf over POST /rpc. Includes both sync (requests) and async (aiohttp) variants.

Looking for the Rust client? The companion crate at rust/ ships the same dual-mode story (live + local) in one package. cargo add libghidra is the Rust equivalent of pip install libghidra. See rust/README.md.

Just want a working wheel? Pre-built per-platform wheels (Linux x86_64 / aarch64, macOS arm64, Windows x64) are attached to every GitHub Release. The top-level README has the per-platform pip install <release-url> commands. The instructions below are for editable installs from a clone (contributors).

pip install -e libghidra/python          # sync only
pip install -e "libghidra/python[async]"  # sync + async
pip install -e "libghidra/python[cli]"    # adds CLI binary helpers
pip install -e "libghidra/python[local]"  # local ELF/PE/Mach-O detection helpers
pip install -e "libghidra/python[async,cli]"

Requires Python 3.12+ and a running LibGhidraHost instance (for the HTTP/RPC client; the local extra plus a built native wheel let you skip the host entirely). The local extra is only needed for offline/native workflows; HTTP-only installs do not pull in binary parser packages.

import libghidra as ghidra

client = ghidra.connect("http://127.0.0.1:18080")

# Check host health
status = client.get_status()
print(f"Connected: {status.service_name} v{status.service_version}")

# Open a program
resp = client.open_program(ghidra.OpenRequest(
    project_path="C:/ghidra_projects",
    project_name="MyProject",
    program_path="binary.exe",
    analyze=True,
))
print(f"Opened: {resp.program_name}")

# List functions
funcs = client.list_functions(limit=10)
for f in funcs.functions:
    print(f"  {f.name} @ 0x{f.entry_address:x}")

# Decompile
dec = client.get_decompilation(funcs.functions[0].entry_address)
print(dec.decompilation.pseudocode)

# Clean up
client.close_program()

Live/headless hosts expose Ghidra project contents separately from the active program. A project can contain many programs, while the normal query/mutation methods operate on exactly one active program.

import libghidra as ghidra

with ghidra.launch_headless(ghidra.HeadlessOptions(
    ghidra_dir="C:/ghidra_dist/ghidra_12.1_DEV",
    project_dir="C:/work/projects",
    project_name="firmware",
    binary="C:/samples/loader.elf",
    binaries=["C:/samples/payload.elf"],
    initial_program="/loader.elf",
)) as host:
    files = host.list_project_files(ghidra.ListProjectFilesRequest(programs_only=True))
    for item in files.files:
        print(item.path)

    host.close_program(ghidra.ShutdownPolicy.SAVE)
    host.open_program(ghidra.OpenRequest(
        project_path="C:/work/projects",
        project_name="firmware",
        program_path="/payload.elf",
    ))

Use absolute Ghidra domain paths (/folder/name) for project programs. See examples/project_files.py for a runnable version.

import asyncio
from libghidra.async_client import AsyncGhidraClient
from libghidra import ConnectOptions

async def main():
    async with AsyncGhidraClient(ConnectOptions()) as client:
        status = await client.get_status()
        funcs = await client.list_functions(limit=5)
        for f in funcs.functions:
            print(f"{f.name} @ 0x{f.entry_address:x}")

asyncio.run(main())

The package installs a libghidra command for quick checks and shell-friendly workflows. Connected commands talk to a running LibGhidraHost:

libghidra status --url http://127.0.0.1:18080
libghidra functions --url http://127.0.0.1:18080 --limit 20
libghidra decompile --url http://127.0.0.1:18080 0x140001000

The CLI also includes small offline binary helpers:

libghidra info sample.exe --sections --imports
libghidra strings sample.exe --min-length 6
libghidra disasm sample.exe entry --count 30

If the native local backend is available, functions and decompile can run without a Ghidra host:

libghidra functions --local sample.exe
libghidra decompile --local sample.exe 0x401000

LocalClient auto-detects ELF, PE, Mach-O, and raw data inputs. You can still pass language_id explicitly on OpenProgramRequest for unusual targets.

Use --format json or --format csv on supported commands for scripting.

• Broad sync API coverage across the host service areas
• Async client coverage for the core read/write, decompiler, listing, memory, session, symbols, xrefs, and type flows
• Binary protobuf transport (same as C++ and Rust clients)
• libghidra command for status checks, function listing, decompilation, binary info, strings, and disassembly
• Retry with exponential backoff and jitter
• Typed dataclass models (decoupled from protobuf)
• Semantic error codes matching the RPC protocol
• Async context manager support (async with)

See examples/ for the full set of Python scripts.

For the full method-by-method reference, see the API Reference.

This table describes the synchronous client. The async client mirrors the core host operations but does not expose every newer helper method yet.