> 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/core/debugger/tutorials/debugging-with-qemu.md).

# Debugging with QEMU

QEMU can emulate a variety of processors (ARM, MIPS, PowerPC, and more), which makes it a convenient way to debug small, isolated code snippets, without needing the original target hardware or a full running program. IDA can automatically launch QEMU and connect to it as a remote GDB target using the ["Run a program before starting debugging"](/core/debugger/concepts/remote-debugging/remote-gdb-debugger/external-programs-and-gdb-debugger.md) option.

1. Download and install QEMU. Windows builds can be downloaded from <https://qemu.weilnetz.de/w64/>.
2. Edit the `cfg\gdb_arch.cfg` file and change the `set QEMUPATH` line to point to the install directory of QEMU.
3. In [Remote GDB Debugger options](/core/debugger/concepts/remote-debugging/remote-gdb-debugger/remote-gdb-debugger-options.md) (**Debugger → Debugger options... → Set specific options**), enable "Run a program before starting debugging".
4. Click "Choose a configuration" and select a predefined configuration. For some configurations, a variant labeled "for snippets" is available. Choose that one when present.
5. If necessary, edit the command line or memory map.
6. Click "OK" twice: once to confirm the GDB configuration dialog, and once more to close the Debugger options dialog.
7. In **Debugger → Process options** make sure that **Hostname** is set to "localhost" and port is non-zero.
8. Select the code range to emulate or at least the first instruction. Alternatively, you can rename the starting address "ENTRY" and end address as "EXIT".
9. Choose **Debugger → Start process** or press <kbd>F9</kbd>.

IDA will write the database into an ELF file (if `%e` was specified), start QEMU with the specified command line and connect to its GDB stub. It will set the SP and PC values so that the code can be stepped through.

## Limitations

While it can be very useful, QEMU emulation has certain limitations:

* The memory map is usually fixed at compile time. So if your program addresses intersect some of the system regions as specified by the memory map, IDA will refuse to start debugging. In that case, you can either rebase the program so that it fits into RAM regions or check other QEMU board configurations for a compatible memory layout.
* The emulation starts at the system (kernel) level when there is no OS loaded. That means that system calls and imported functions will not work.
* The hardware access will only work to the extent emulated by QEMU. If the code you are emulating does not match the chosen board configuration of QEMU, the code accessing the hardware most likely will not work properly, if at all.

See also:

* [External programs and GDB Debugger](/core/debugger/concepts/remote-debugging/remote-gdb-debugger/external-programs-and-gdb-debugger.md)
* [Remote GDB Debugger](/core/debugger/concepts/remote-debugging/remote-gdb-debugger.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 dynamically by asking a question.

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

```
GET https://docs.hex-rays.com/core/debugger/tutorials/debugging-with-qemu.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.