> For the complete documentation index, see [llms.txt](https://docs.hex-rays.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/getting-started.md).

# Getting Started

Install IDA Pro Headless from its package, connect it to your license server, and analyze your first binary from Python and from `idat`.

Every package includes a `README.md` that walks through the same steps for its platform. This page follows it on Linux, with the Windows commands alongside.

**At a glance**, you will:

1. Download and unzip the package for your platform.
2. Accept the IDA license agreement.
3. Install IDA's Python module in a virtual environment.
4. Point IDA Pro Headless to your license server.
5. Check the license, then analyze a binary.

It takes a few minutes, plus about a minute the first time IDA loads.

## Prerequisites

* An IDA Pro Headless license, with its headless seats on your license server. See [License](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/overview.md#license).
* A Hex-Rays license server, **version 9.5.2 or later**, that the machine can reach. See [Headless License Server setup](https://docs.hex-rays.com/editions-and-licenses/license-server/admin/headless-license-server-setup.md).
* The **host** and **port** of that license server. Ask your administrator: the license server console shows them on its **Dashboard**.
* Python 3.8 or later.
* On Linux, glibc 2.28 or later.
* About 1.5 GB of free disk space while you download and unpack the package. Once unpacked, it takes about 800 MB.

{% hint style="info" %}
Check that the machine can reach the license server before you start: `nc -vz <host> <port>` on Linux and macOS, or `Test-NetConnection <host> -Port <port>` on Windows. In a virtual machine or a container, run the check from inside it.
{% endhint %}

## Download the package

1. Log in to the [My Hex-Rays portal](https://my.hex-rays.com/) and open the **Download center**.
2. Under **Installers → Release**, open the **IDA Pro Headless** folder and the folder of the newest version, for example **9.5**.
3. Download the package for your platform, for example **IDA Pro Headless linux:x86\_64 9.5**. There is one zip per platform: Linux x64, Linux arm64, macOS on Apple silicon and Windows x64. See [Package contents](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/reference/package-contents.md#supported-platforms).
4. Unzip it where you want IDA Pro Headless to live.

{% hint style="info" icon="desktop-arrow-down" %}

### Quick download with HCLI

[HCLI](https://hcli.docs.hex-rays.com/) downloads the package from the terminal, which is handy on a server without a browser. Run it, log in, and pick the **IDA Pro Headless** package for your platform:

```bash
uvx ida-hcli login
uvx ida-hcli download --output-dir ~/
```

On a machine where nobody can log in (CI, Docker builds, cloud VMs), use an API key instead: create one with `hcli auth key create --name ida-headless` and export it as `HCLI_API_KEY`. Pass the package's asset key to `hcli download` to skip the interactive list; `hcli download --list-tags` shows the tags available to you.
{% endhint %}

{% hint style="info" %}
On Windows, Explorer's **Extract All** can add a second folder level with the same name. Use the inner folder, the one that holds `README.md`.
{% endhint %}

## Step 1: Accept the license agreement

Run every command from the package folder, the one that holds `README.md` and `setup.sh`. The setup script records your acceptance of the IDA license agreement for the current user, and prints the next commands with the paths of your installation.

{% tabs %}
{% tab title="Linux, macOS" %}

```bash
cd ~/ida-pro-headless-9.5-x64linux
./setup.sh --accept-eula
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
cd ida-pro-headless-9.5-x64win
.\setup.ps1 -AcceptEula
```

{% endtab %}
{% endtabs %}

```
Recording the license agreement: this loads IDA once, which can take a minute the first time...
The IDA license agreement is now accepted for analyst (EULA 95).

Next, in a virtual environment outside this folder, install IDA's Python module
and set IDADIR:
  pip install ".../ida-pro-headless-9.5/idalib/python/idapro-0.0.11-py3-none-any.whl"
  export IDADIR=".../ida-pro-headless-9.5"
```

{% hint style="info" %}
Copy the commands the script prints: they hold the exact paths and file names of your package.
{% endhint %}

## Step 2: Install IDA's Python module

The `idapro` module ships in the package, so this step works offline. Create the virtual environment **outside** the package folder.

{% tabs %}
{% tab title="Linux, macOS" %}

```bash
python3 -m venv ~/.venvs/ida-pro-headless
. ~/.venvs/ida-pro-headless/bin/activate
pip install ida-pro-headless-9.5/idalib/python/idapro-0.0.11-py3-none-any.whl
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
py -m venv $HOME\.venvs\ida-pro-headless
& $HOME\.venvs\ida-pro-headless\Scripts\Activate.ps1
pip install ida-pro-headless-9.5\idalib\python\idapro-0.0.11-py3-none-any.whl
```

{% endtab %}
{% endtabs %}

Without a virtual environment, set `PYTHONPATH` to the `idalib/python` folder of the installation instead of installing the module.

## Step 3: Tell it where IDA and the license server are

Set two environment variables: `IDADIR`, the IDA folder inside the package, and `IDA_LICENSE`, your license server. Ask your administrator for the host and port.

{% tabs %}
{% tab title="Linux, macOS" %}

```bash
export IDADIR="$PWD/ida-pro-headless-9.5"
export IDA_LICENSE=server:host=licsrv.example.com:port=65434:instance=my-pipeline
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
$env:IDADIR = "$PWD\ida-pro-headless-9.5"
$env:IDA_LICENSE = "server:host=licsrv.example.com:port=65434:instance=my-pipeline"
```

{% endtab %}
{% endtabs %}

The `instance` part is optional. It names the seat on the license server, so you can tell your scripts and agents apart in the administration console. See [Environment variables](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/reference/environment-variables.md#ida_license).

{% hint style="info" %}
These variables last for the current terminal only. To keep them, add them to your shell profile, or to the environment of the service, CI job or container that runs your scripts.
{% endhint %}

## Step 4: Check the license

`examples/check_license.py` takes a seat, prints what the license covers, and gives the seat back. It needs no binary.

```
$ python examples/check_license.py
License  XX-XXXX-XXXX-XX (floating)
Product  IDAPROHEADLESS, edition ida-pro-headless
Valid    2026-10-01 to 2027-10-01
Add-ons  HEXCX64, HEXCX86, TEAMS, LUMINA
Seat     my-pipeline from licsrv.example.com:65434
```

If it exits with an error, see [Troubleshooting](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/reference/troubleshooting.md).

## Step 5: Analyze a binary

### From Python

`examples/list_functions.py` analyzes a binary and lists its functions. It builds the database from a temporary copy, so your original file is left untouched.

```
$ python examples/list_functions.py /bin/ls | tail -3
0x238c8  __gmon_start__
0x238d0  _ITM_registerTMCloneTable
471 functions in /bin/ls, seat my-pipeline from licsrv.example.com:65434
```

Your own scripts follow the same pattern. Import `idapro` **first**, before any other IDA module, and always close the database, even when your script fails, so the seat goes back to the pool:

```python
import idapro  # must be first
import ida_auto, idautils

if idapro.open_database("/path/to/sample", True) != 0:
    raise SystemExit("could not open the database")
try:
    ida_auto.auto_wait()
    print(sum(1 for _ in idautils.Functions()), "functions")
finally:
    idapro.close_database()
```

{% hint style="info" %}
Work on a copy of your binary: IDA writes its database next to the file it opens.
{% endhint %}

You can also use the higher-level [Domain API](https://docs.hex-rays.com/developer/domain-api.md): `pip install ida-domain` in the same virtual environment. It keeps the `idapro` module from the package.

### In batch mode with idat

`idat` opens a binary, runs an IDAPython script and exits:

```python
# my_script.py
import ida_auto, ida_pro, idautils
ida_auto.auto_wait()
print("functions:", sum(1 for _ in idautils.Functions()))
ida_pro.qexit(0)
```

{% tabs %}
{% tab title="Linux, macOS" %}

```bash
ida-pro-headless-9.5/idat -A -S"$HOME/my_script.py" -L"$HOME/work/ida.log" ~/work/sample
grep functions: ~/work/ida.log
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
.\ida-pro-headless-9.5\idat.exe -A -S"$HOME\my_script.py" -L"$HOME\work\ida.log" $HOME\work\sample.exe
Select-String functions: $HOME\work\ida.log
```

{% endtab %}
{% endtabs %}

`-A` runs IDA without any dialog, `-S` runs your script once the database is loaded, and `-L` writes IDA's output to a log file. `idat` uses the same `IDA_LICENSE` as your Python scripts.

See [Command line switches](https://docs.hex-rays.com/core/user-interface/concepts/command-line-switches.md) for the other `idat` options.

## Check your setup

You are ready when:

* [ ] `setup.sh --accept-eula` (or `setup.ps1 -AcceptEula`) reported that the license agreement is accepted.
* [ ] `pip install` installed the `idapro` module in your virtual environment.
* [ ] `examples/check_license.py` printed your license and your seat.
* [ ] `examples/list_functions.py` listed the functions of a binary.
* [ ] With `instance=<name>` set, your seat showed on the **Allocations** page of the license server console while the database was open.

## Update or remove

Each new build ships as a new package. Unzip it next to the previous one, run the setup script again, install its `idapro` module, and point `IDADIR` to it. To remove IDA Pro Headless, delete the package folder and the virtual environment. The `README.md` of the package gives the details for your platform.

## What's next?

* [Headless seats](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/concepts/headless-seats.md): how many seats your scripts and agents need.
* [Use IDA Pro Headless with coding agents](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/how-tos/use-with-coding-agents.md)
* [Run IDA Pro Headless in Docker](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/how-tos/run-in-docker.md)
* [Work offline with a borrowed seat](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/how-tos/work-offline.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/getting-started.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
