## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Getting started with IDAPython

# Intro

The IDAPython API provides you a range of functions to interact with the disassembler, navigate through the output, and manipulate various elements such as functions, instructions, data, and comments.

This guide is is designed to speed up the learning curve in IDAPython and kickstart your journey with scripting in IDA, assuming that you are already found your way around IDA and got familiar with IDA basics.

Our IDA SDK is open source and available on GitHub.

## How this guide is structured?

First, check basics for the core concepts like common variables, then dive into our simple, short and reusable code snippets showing basic examples of commonly used functions.

### Where can I find the complete examples library?

When you feel comfortable with most popular IDAPython API usage, you can delve into our set of more complex examples. The full library of our examples is shipped with your IDA instance in the python/examples folder. You can find them also in the GitHub repository.

# Basics

## Common modules

IDAPython API is organized in modules, however their number may be a bit overwhelming for the first sigh. Here’s the list of modules that should catch your attention first:

- `idautils`: This module extracts the most useful and handy functions allowing you to jump right away and interact with the disassembly without the need to scrutinize the whole IDAPython API from the start. You can find here functions to iterate through whole segments, functions (founded by IDA and also user-defined), named locations, etc.

- `ida_idaapi`: The `ida_idaapi` module comes handy when you want to create custom plugins or handle events, as it gives you access to more advanced functions and allows interaction with overall system

- `idc`: This module provides functions that were originally part of native IDA IDC scripting language, wrapped for use in IDAPython API. This is a great starting point if you’re already familiar with IDC scripting.

- `ida_funcs`: This module gives you tools to create and manipulate functions within IDA.

- `ida_kernwin`: This module provides functionality to interact with IDA UI, so you can create custom dialogs and more.

## Common variables and constants

When you start working with IDAPython, you’ll realize that one of the most commonly passed variables is `ea`, which refers to the valid memory address (effective address). On the other hand, the `BADADDR` is a constant that indicates an invalid address. It is used to indicate that an operation (such as querying a function) has failed or returned an invalid result, or signify that a specific memory location is unusable. Whenever you’re working with functions that return memory addresses, it’s a best practice to check whether the result equals BADADDR to ensure the operation was successful.

# Code snippets

Here you can check the most common functions grouped by topics and short code samples that can serve as building blocks for longer scripts. They are usually focused on performing one specific action and can be easily reusable in more complex scripts, which you can find later under examples.

## Part 1: Navigating the disassembly—addresses and names

### Get the current address:**

    ea = idc.here()  # Get the current address
    print(f"Current address: {hex(ea)}")

    idc.get_screen_ea()

## Set the current address

    idc.jumpto(0x401000)  # Jump to address 0x401000

### Get the minimum address in IDB

    idc.get_inf_attr(INF_MIN_EA)

### Get the maximum address in IDB

    idc.get_inf_attr(INF_MAX_EA)

### List all instruction addresses

    for ea in idautils.Heads():
      print(hex(ea))

### Get the name associated with a given address

    ida_name.get_name(0x100000da0)

### Get the address associated with a given name

    ida_name.get_name_ea(0, "_main")

## Part 2: Reading and Writing Data

### Reading Bytes and Words

    byte_value = idc.get_wide_byte(0x401000)  # Read a byte at address 0x401000
    word_value = idc.get_wide_word(0x401002)  # Read a word (2 bytes) at address 0x401002
    dword_value = idc.get_wide_dword(0x401004)  # Read a double word (4 bytes) at address 0x401004

    print(f"Byte: {byte_value}, Word: {word_value}, Dword: {dword_value}")

### Writing Bytes and Words

    idc.patch_byte(0x401000, 0x90)  # Write a byte (0x90) at address 0x401000
    idc.patch_word(0x401002, 0x9090)  # Write a word (0x9090) at address 0x401002
    idc.patch_dword(0x401004, 0x90909090)  # Write a double word (0x90909090) at address 0x401004

## Part 3: Comments

## Add a regular (non-repetable) or repeatable comment

    idc.set_cmt(0x401000, "This is a comment", 0)  # Add a regular comment at address 0x401000
    idc.set_cmt(0x401000, "This is a repeatable comment", 1)  # Add a repeatable comment at address 0x401000

### Get a regular comment

    comment = idc.get_cmt(0x401000, 0)  # Get a regular comment at address 0x401000
    print(f"Comment: {comment}")

## Segments

### Get a segment name

    idc.get_segm_name(ea)

### Get the first segment address:

`get_first_seg()`

### Iterate through all segments and return segment names

    for seg in idautils.Segments(): print (idc.get_segm_name(seg))

### Add segment

## Part X: Functions

### Create and delete function

    idc.add_func(0x401000, 0x401050)  # Create a function starting at 0x401000 and ending at 0x401050
    idc.del_func(0x401000)  # Delete the function at 0x401000

### Get the name of the function

    get_func_name(ea)

### Iterate through all functions and print their effective addresses and names

    for func_ea in idautils.Functions(): func_name = idc.get_func_name(func_ea); print(hex(func_ea), func_name)

## Part: Navigating cross-references (Xrefs)

### List cross-references to an address

    for xref in idautils.XrefsTo(0x401000):
        print(f"Xref to 0x401000 from {hex(xref.frm)}")

### List cross-references from an address:**

    for xref in idautils.XrefsFrom(0x401000):
        print(f"Xref from 0x401000 to {hex(xref.to)}")

### Iterate through all cross-references to the specific address and print the address from where the reference originates.

    for ref in idautils.XrefsTo(ea):
      print(hex(ref.frm))

## Part X: UI

### Set background color of a function

    set_color(0x401000, idc.CIC_FUNC, 0x007fff)  # Set background color for the function starting at address 0x401000

### Display a custom dialog

    ida_kernwin.info("This is a custom message dialog. Good luck with learning IDAPython API!")

# Complex script examples

If you feel more comfortable with IDAPython now, you can delve into more complex and advanced examples shipped with your IDA instance. You can find them in the `python/examples` folder where your IDA is installed or check them from our docs. These collection gathered more advanced code samples, which usually make use of more modules and APIs.

# What’s next?

Delve into our tutorial on how to create your first custom plugin in IDAPython.