# qilingframework/qiling architecture

> Architecture diagram of the GitHub repository qilingframework/qiling, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qilingframework/qiling
- Repository: https://github.com/qilingframework/qiling

## Overview

Qiling is a Python binary-emulation and analysis framework built on Unicorn. A user configures a Qiling instance with a binary, root filesystem, platform, and architecture; the core coordinates loading, machine state, and emulation, while OS services and optional hardware models support the guest. Instrumentation, debugging, patching, and analysis extensions build on that runtime. The README documents broad platform, format, and analysis capabilities; some subsystem links below rely on that documentation because their implementation was not sampled.

Main entry points: [`qiling/core.py`](https://github.com/qilingframework/qiling/blob/master/qiling/core.py) (Qiling runtime), [`qiling/os/os.py`](https://github.com/qilingframework/qiling/blob/master/qiling/os/os.py) (OS runtime), [`qiling/loader/loader.py`](https://github.com/qilingframework/qiling/blob/master/qiling/loader/loader.py) (Binary loaders), [`qiling/os/memory.py`](https://github.com/qilingframework/qiling/blob/master/qiling/os/memory.py) (Guest memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Emulation runtime"]
  node_core["Qiling runtime<br/>[core.py]"]
  node_arch["CPU architectures"]
  node_memory["Guest memory<br/>[memory.py]"]
  node_structs["Core structures<br/>[struct.py]"]
  node_loader["Binary loaders<br/>[loader.py]"]
  node_formats["Executable formats"]
  node_hooks["Hook dispatch<br/>[core_hooks.py]"]
end

subgraph group_platform["Guest platforms"]
  node_os["OS runtime<br/>[os.py]"]
  node_linux["Linux services"]
  node_windows["Windows services"]
  node_macos["macOS services"]
  node_firmware["MCU platforms"]
  node_uefi["UEFI services"]
end

subgraph group_devices["Device emulation"]
  node_hardware["Virtual hardware<br/>[hw.py]"]
  node_mcu_models["MCU models"]
end

subgraph group_analysis["Analysis tools"]
  node_debugger["Debuggers"]
  node_coverage["Coverage tools"]
  node_tracing["Execution tracing"]
  node_ida["IDA integration<br/>[qilingida.py]"]
end

subgraph group_extensions["Extensions"]
  node_fuzzing["AFL fuzzing"]
  node_sanitizers["Heap sanitizer<br/>[heap.py]"]
end

node_user(("Framework user"))

node_user -->|"configures and runs"| node_core
node_core -->|"initializes"| node_arch
node_core -->|"initializes"| node_memory
node_core -->|"runs loader"| node_loader
node_core -->|"initializes"| node_os
node_core -->|"initializes"| node_hardware
node_core -->|"inherits hooks"| node_hooks
node_structs -->|"reads and writes"| node_memory
node_loader -.->|"loads binaries"| node_formats
node_loader -.->|"maps images"| node_memory
node_os -.->|"selects platform"| node_linux
node_os -.->|"selects platform"| node_windows
node_os -.->|"selects platform"| node_macos
node_os -.->|"selects platform"| node_firmware
node_os -.->|"selects platform"| node_uefi
node_firmware -.->|"models boards"| node_mcu_models
node_mcu_models -.->|"uses peripherals"| node_hardware
node_user -.->|"debugs execution"| node_debugger
node_user -.->|"analyzes coverage"| node_coverage
node_user -.->|"traces execution"| node_tracing
node_user -->|"integrates analysis"| node_ida
node_user -.->|"fuzzes binaries"| node_fuzzing
node_user -.->|"checks heap use"| node_sanitizers
node_core -->|"dispatches callbacks"| node_hooks

click node_core "https://github.com/qilingframework/qiling/blob/master/qiling/core.py"
click node_arch "https://github.com/qilingframework/qiling/tree/master/qiling/arch"
click node_memory "https://github.com/qilingframework/qiling/blob/master/qiling/os/memory.py"
click node_structs "https://github.com/qilingframework/qiling/blob/master/qiling/os/struct.py"
click node_loader "https://github.com/qilingframework/qiling/blob/master/qiling/loader/loader.py"
click node_formats "https://github.com/qilingframework/qiling/tree/master/qiling/loader"
click node_hooks "https://github.com/qilingframework/qiling/blob/master/qiling/core_hooks.py"
click node_os "https://github.com/qilingframework/qiling/blob/master/qiling/os/os.py"
click node_linux "https://github.com/qilingframework/qiling/tree/master/qiling/os/linux"
click node_windows "https://github.com/qilingframework/qiling/tree/master/qiling/os/windows"
click node_macos "https://github.com/qilingframework/qiling/tree/master/qiling/os/macos"
click node_firmware "https://github.com/qilingframework/qiling/tree/master/qiling/os/mcu"
click node_uefi "https://github.com/qilingframework/qiling/tree/master/qiling/os/uefi"
click node_hardware "https://github.com/qilingframework/qiling/blob/master/qiling/hw/hw.py"
click node_mcu_models "https://github.com/qilingframework/qiling/tree/master/qiling/extensions/mcu"
click node_debugger "https://github.com/qilingframework/qiling/tree/master/qiling/debugger"
click node_coverage "https://github.com/qilingframework/qiling/tree/master/qiling/extensions/coverage"
click node_tracing "https://github.com/qilingframework/qiling/tree/master/qiling/extensions/tracing"
click node_ida "https://github.com/qilingframework/qiling/blob/master/qiling/extensions/idaplugin/qilingida.py"
click node_fuzzing "https://github.com/qilingframework/qiling/tree/master/qiling/extensions/afl"
click node_sanitizers "https://github.com/qilingframework/qiling/blob/master/qiling/extensions/sanitizers/heap.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core,node_arch,node_memory,node_structs,node_loader,node_formats,node_hooks,node_user toneBlue
class node_os,node_linux,node_windows,node_macos,node_firmware,node_uefi toneAmber
class node_hardware,node_mcu_models toneMint
class node_debugger,node_coverage,node_tracing,node_ida toneRose
class node_fuzzing,node_sanitizers toneIndigo
```

## Components

### Emulation runtime

- [Qiling runtime](https://github.com/qilingframework/qiling/blob/master/qiling/core.py): `qiling/core.py`
- [CPU architectures](https://github.com/qilingframework/qiling/tree/master/qiling/arch): `qiling/arch`
- [Guest memory](https://github.com/qilingframework/qiling/blob/master/qiling/os/memory.py): `qiling/os/memory.py`
- [Core structures](https://github.com/qilingframework/qiling/blob/master/qiling/os/struct.py): `qiling/os/struct.py`
- [Binary loaders](https://github.com/qilingframework/qiling/blob/master/qiling/loader/loader.py): `qiling/loader/loader.py`
- [Executable formats](https://github.com/qilingframework/qiling/tree/master/qiling/loader): `qiling/loader`
- [Hook dispatch](https://github.com/qilingframework/qiling/blob/master/qiling/core_hooks.py): `qiling/core_hooks.py`

### Guest platforms

- [OS runtime](https://github.com/qilingframework/qiling/blob/master/qiling/os/os.py): `qiling/os/os.py`
- [Linux services](https://github.com/qilingframework/qiling/tree/master/qiling/os/linux): `qiling/os/linux`
- [Windows services](https://github.com/qilingframework/qiling/tree/master/qiling/os/windows): `qiling/os/windows`
- [macOS services](https://github.com/qilingframework/qiling/tree/master/qiling/os/macos): `qiling/os/macos`
- [MCU platforms](https://github.com/qilingframework/qiling/tree/master/qiling/os/mcu): `qiling/os/mcu`
- [UEFI services](https://github.com/qilingframework/qiling/tree/master/qiling/os/uefi): `qiling/os/uefi`

### Device emulation

- [Virtual hardware](https://github.com/qilingframework/qiling/blob/master/qiling/hw/hw.py): `qiling/hw/hw.py`
- [MCU models](https://github.com/qilingframework/qiling/tree/master/qiling/extensions/mcu): `qiling/extensions/mcu`

### Analysis tools

- [Debuggers](https://github.com/qilingframework/qiling/tree/master/qiling/debugger): `qiling/debugger`
- [Coverage tools](https://github.com/qilingframework/qiling/tree/master/qiling/extensions/coverage): `qiling/extensions/coverage`
- [Execution tracing](https://github.com/qilingframework/qiling/tree/master/qiling/extensions/tracing): `qiling/extensions/tracing`
- [IDA integration](https://github.com/qilingframework/qiling/blob/master/qiling/extensions/idaplugin/qilingida.py): `qiling/extensions/idaplugin/qilingida.py`

### Extensions

- [AFL fuzzing](https://github.com/qilingframework/qiling/tree/master/qiling/extensions/afl): `qiling/extensions/afl`
- [Heap sanitizer](https://github.com/qilingframework/qiling/blob/master/qiling/extensions/sanitizers/heap.py): `qiling/extensions/sanitizers/heap.py`

### Other components

- **Framework user**

## Connections

- Framework user → Qiling runtime: configures and runs (evidence: `README.md`)
- Qiling runtime → CPU architectures: initializes (evidence: `qiling/core.py`)
- Qiling runtime → Guest memory: initializes (evidence: `qiling/core.py`)
- Qiling runtime → Binary loaders: runs loader (evidence: `qiling/core.py`)
- Qiling runtime → OS runtime: initializes (evidence: `qiling/core.py`)
- Qiling runtime → Virtual hardware: initializes (evidence: `qiling/core.py`)
- Qiling runtime → Hook dispatch: inherits hooks (evidence: `qiling/core.py`)
- Core structures → Guest memory: reads and writes (evidence: `qiling/os/struct.py`)
- Binary loaders → Executable formats: loads binaries (evidence: `README.md`)
- Binary loaders → Guest memory: maps images
- OS runtime → Linux services: selects platform (evidence: `README.md`)
- OS runtime → Windows services: selects platform (evidence: `README.md`)
- OS runtime → macOS services: selects platform (evidence: `README.md`)
- OS runtime → MCU platforms: selects platform (evidence: `README.md`)
- OS runtime → UEFI services: selects platform (evidence: `README.md`)
- MCU platforms → MCU models: models boards
- MCU models → Virtual hardware: uses peripherals
- Framework user → Debuggers: debugs execution (evidence: `README.md`)
- Framework user → Coverage tools: analyzes coverage (evidence: `README.md`)
- Framework user → Execution tracing: traces execution (evidence: `README.md`)
- Framework user → IDA integration: integrates analysis (evidence: `qiling/extensions/idaplugin/qilingida.py`)
- Framework user → AFL fuzzing: fuzzes binaries (evidence: `README.md`)
- Framework user → Heap sanitizer: checks heap use
- Qiling runtime → Hook dispatch: dispatches callbacks (evidence: `qiling/core_hooks.py`)