IDA Domain

The IDA Domain API is a new open-source Python API designed to make scripting in IDA simpler, more consistent, and more natural.

This is a first step in a much longer journey. It’s not the finish line, but a foundation for ongoing collaboration between Hex-Rays and the reverse engineering community. Over time, the Domain API will expand to cover more areas of IDA, gradually becoming the main entry point for scripting and plugin development.

The Domain in Domain API refers to the domain of reverse engineering. Concepts like functions, types, cross-references, and more are first-class citizens in this API, giving you cleaner, domain-focused abstractions for common tasks.

The Domain API sits on top of the IDA Python SDK, complementing it rather than replacing it. You can use both side by side—combining the clarity and simplicity of Domain API calls with the full flexibility of the SDK when needed.

Compatibility: Requires IDA Pro 9.1.0 or later

🚀 Key Features

• Domain-focused design – Work directly with core reverse engineering concepts like functions, types, and xrefs as first-class citizens.
• Open source from day one – Read the code, suggest improvements, or contribute new ideas.
• Pure Python implementation – No compilation required, works with modern Python versions.
• Compatible by design – Use alongside the IDA Python SDK without conflicts.
• Developer-centric – Reduce boilerplate and streamline frequent tasks.
• Independently versioned – Upgrade at your own pace and pin versions for stability.
• Simple installation – Get started with a single pip install.

📦 Installation

Prerequisites

IDA Pro Version: The IDA Domain library requires IDA Pro 9.1.0 or later.

The idapro Python module needs to know where IDA Pro is installed. The location is stored in a per-user config file (%APPDATA%\Hex-Rays\IDA Pro\ida-config.json on Windows, ~/.idapro/ida-config.json on Linux/macOS).

• If IDA was installed via HCLI: the install path is configured automatically — no further setup is required.

• Otherwise: run the py-activate-idalib.py activation script that ships with IDA once. It auto-detects the install directory from its own location and writes it to the per-user config. The script normally lives in <IDA install dir>/idalib/python/:

  Linux/macOS:

  python3 "/path/to/ida/idalib/python/py-activate-idalib.py"
  

  Windows:

  python "C:\Program Files\IDA Professional 9.1\idalib\python\py-activate-idalib.py"
  

  You can also pass -d <ida-install-dir> to point at a specific IDA installation explicitly.

Install from PyPI

pip install ida-domain

Overriding the IDA install directory with IDADIR

To override the configured install directory for a single session or script — for example to test a specific IDA build, switch between multiple installed versions, or in CI — set the IDADIR environment variable before importing idapro:

Linux/macOS:

export IDADIR="/path/to/your/ida/installation"

Windows:

set "IDADIR=C:\Program Files\IDA Professional 9.1"

Example paths:

• macOS: /Applications/IDA Professional 9.1.app/Contents/MacOS/
• Windows: C:\Program Files\IDA Professional 9.1\
• Linux: /opt/ida-9.1/

Important: Set IDADIR only for the current shell session or inside the script that uses idapro — do not set it as a persistent/global environment variable (e.g. via ~/.bashrc, ~/.zshrc, or Windows System Properties). A globally exported IDADIR can interfere with the IDA GUI and other IDA tools on your system.

🎯 Usage Example

Here is an example showing how to use IDA Domain to analyze a binary:

#!/usr/bin/env python3
"""
Database exploration example for IDA Domain API.

This example demonstrates how to open an IDA database and explore its basic properties.
"""

import argparse
from dataclasses import asdict

import ida_domain
from ida_domain import Database
from ida_domain.database import IdaCommandOptions


def explore_database(db_path):
    """Explore basic database information."""
    ida_options = IdaCommandOptions(auto_analysis=True, new_database=False)
    with Database.open(db_path, ida_options) as db:
        # Get basic information
        print(f'Address range: {hex(db.minimum_ea)} - {hex(db.maximum_ea)}')

        # Get metadata
        print('Database metadata:')
        metadata_dict = asdict(db.metadata)
        for key, value in metadata_dict.items():
            print(f'  {key}: {value}')

        # Count functions
        function_count = 0
        for _ in db.functions:
            function_count += 1
        print(f'Total functions: {function_count}')


def main():
    """Main entry point with argument parsing."""
    parser = argparse.ArgumentParser(description='Database exploration example')
    parser.add_argument(
        '-f', '--input-file', help='Binary input file to be loaded', type=str, required=True
    )
    args = parser.parse_args()
    explore_database(args.input_file)


if __name__ == '__main__':
    main()

📖 Documentation

Complete documentation is available at: https://ida-domain.docs.hex-rays.com/

• API Reference: Documentation of available classes and methods
• Getting Started: Complete setup guide including installation and first steps
• Examples: Usage examples for common tasks
• Migration Guide: Migrate from IDA Python SDK to Domain API

🛠️ Development

For development, we use a uv based workflow:

git clone https://github.com/HexRaysSA/ida-domain.git
cd ida-domain
uv sync --extra dev
uv run pre-commit install

🧪 Testing

Run the test suite using pytest:

uv sync --extra dev
uv run pytest

📚 Build Documentation

To build the documentation locally:

uv sync --extra docs
uv run mkdocs serve

Or to just build it,

uv run mkdocs build

The documentation is available in site/

Online Documentation

The latest documentation is available at: https://ida-domain.docs.hex-rays.com/

📝 Examples

Check the examples/ directory for usage examples:

uv run python examples/analyze_database.py

Installed and editable packages can locate the examples programmatically:

from ida_domain import examples_path

examples = examples_path()

Contributing

We welcome contributions! Please see our Contributing Guidelines for details on how to:

• Report bugs and suggest features
• Submit pull requests with proper testing

License

This project is licensed under the MIT License - see the LICENSE file for details.