# Getting Started

## 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](https://docs.hex-rays.com/getting-started/basic-usage).

Our IDA SDK is open source and available on [GitHub](https://github.com/HexRaysSA/ida-sdk).

### How this guide is structured?

First, check [basics](#basics) for the core concepts like common variables, then dive into our simple, short and reusable [code snippets](#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](https://docs.hex-rays.com/developer-guide/idapython/idapython-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](https://github.com/HexRaysSA/IDAPython).

## 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:\*\*

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

```python
idc.get_screen_ea()
```

### Set the current address

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

#### Get the minimum address in IDB

```python
idc.get_inf_attr(INF_MIN_EA)
```

#### Get the maximum address in IDB

```python
idc.get_inf_attr(INF_MAX_EA)
```

#### List all instruction addresses

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

#### Get the name associated with a given address

```python
ida_name.get_name(0x100000da0)
```

#### Get the address associated with a given name

```python
ida_name.get_name_ea(0, "_main")
```

### Part 2: Reading and Writing Data

#### Reading Bytes and Words

```python
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

```python
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

```python
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

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

### Segments

#### Get a segment name

```python
idc.get_segm_name(ea)

```

#### Get the first segment address:

`get_first_seg()`

#### Iterate through all segments and return segment names

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

#### Add segment

### Part X: Functions

#### Create and delete function

```python
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

```python
get_func_name(ea)
```

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

```python
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

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

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

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

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

### Part X: UI

#### Set background color of a function

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

#### Display a custom dialog

```python
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](https://docs.hex-rays.com/developer-guide/idapython/idapython-examples). 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](https://docs.hex-rays.com/developer-guide/idapython/how-to-create-a-plugin).