# 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](https://github.com/astral-sh/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](https://github.com/HexRaysSA/ida-sdk).

**Python** users have two API options on top of idalib:

* [**IDAPython**](/developer/idapython.md) — Use standard IDAPython modules (`ida_funcs`, `ida_segment`, etc.),
* [**Domain API**](/developer/domain-api.md) — Use a higher-level interface built on top of IDAPython SDK.

{% hint style="success" %}
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.
{% endhint %}

**C++** users link directly against idalib via [idalib.hpp](https://cpp.docs.hex-rays.com/idalib_8hpp.html#details) and the IDA C++ SDK.

### Installation Options

There are two ways to install idalib:

* via [**HCLI**](#option-1-hcli) (the recommended, faster way, especially for automated or headless environments), or
* [**manually**](#option-2-manually) from your local IDA installation.

### Option 1: HCLI

[HCLI](https://hex-rays.com/blog/introducing-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](https://hcli.docs.hex-rays.com/getting-started/installation/) installed

Then run:

```bash
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.

{% hint style="info" %}
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.
{% endhint %}

### 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`:

```bash
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:

```bash
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.

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

## First-usage Examples

The [idalib-example](https://github.com/HexRaysSA/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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hex-rays.com/core/idalib/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.