Getting Started

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

This tutorial walks you through installation options, setup, and a first usage example. On a 9.4+ installation of IDA, the installer activates idalib automatically. No extra steps needed.

Prerequisites

• IDA Home, IDA Pro, or IDA Classroom.

• 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 three ways to install idalib:

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

• manually from your local IDA installation, or

• automatically during a 9.4+ installation of IDA (no further steps needed).

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 \
    --create-python-environment \
    --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 installation directory and then run the activation script once. You can use uv or a regular Python virtual environment.

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"

Option 3: Automatically

Starting with version 9.4, the installer can activate idalib automatically. Leave the checkbox Use this installation as the default for idalib checked during installation and you are ready to use idalib. No further steps required.

activate idalib during installation

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 installation directory.