Getting Started

Get up and running with idalib — the IDA headless automation interface that allows you to use the IDA Pro analysis engine without launching IDA's GUI.

This tutorial walks you through installation, setup, and a first usage example.

Prerequisites

• IDA Pro 9.0 or newer

• uv (recommended) or pip

Installation

The idalib is the core library that lets you use IDA headlessly. It exposes a small lifecycle API (initialize, open a database, analyze, close), and from there you work against the IDA SDK.

Python users have two API options on top of idalib:

• IDAPython — Use standard IDAPython modules (ida_funcs, ida_segment, etc.),

• Domain API — Use a higher-level interface built on top of IDAPython SDK.

If you're not sure where to start, use Python. It gives you access to both the IDAPython API and the beginner-friendly Domain API.

C++ users link directly against idalib via idalib.hpp and the IDA C++ SDK.

Installation Options

There are two ways to install idalib:

• via HCLI (the recommended, faster way, especially for automated or headless environments), or

• manually from your local IDA installation.

Option 1: HCLI

HCLI is the official command-line interface for managing Hex-Rays software, licenses, and plugins. It can download IDA, install it, and activate idalib automatically, with no GUI required.

You'll need:

• HCLI installed

Then run:

hcli login

hcli ida install \
    --download-id ida-pro:latest \
    --set-default \
    --accept-eula \
    --yes

uv pip install idapro

HCLI also handles the idalib activation step automatically, so you do not need to run py-activate-idalib.py separately.

For headless environments (Docker, CI/CD), use an API key instead of hcli login: create one with hcli auth key create --name my-key, export it as HCLI_API_KEY, and add --license-id to the install command if needed.

Option 2: Manually

If you manage your IDA installation yourself, install the idapro package from your IDA Pro installation directory and then run the activation script once. You can use uv or a regular Python virtual environment.

With uv:

uv sync
# macOS
uv run "/Applications/IDA Professional 9.3.app/Contents/MacOS/idalib/python/py-activate-idalib.py"
# Windows
uv run "C:\Program Files\IDA Professional 9.3\idalib\python\py-activate-idalib.py"

With a regular virtual environment:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install idapro
python /path/to/IDA/installation/py-activate-idalib.py

Using idalib in your script

Once installed, you're ready to use idalib. Make sure to import idapro as the first import in your script, before any other IDA modules.

import idapro  # must be first
import ida_funcs
import ida_auto
# ...

First-usage Examples

The idalib-example repository provides a minimal starting point, with simple scripts demonstrating two approaches: one using standard IDAPython modules, and another using the Domain API. Both examples load an input file, trigger auto-analysis, and print the discovered functions.

For more advanced use cases, refer to the idalib/examples folder in your IDA Pro installation directory.