# ImHex User Guide

ImHex is a hex editor built for reverse engineers, programmers, and anyone who
needs to inspect, edit, and understand binary data — without burning their
retinas during a 3 AM debugging session. It pairs a feature-dense hex editor
with a custom C++-like **Pattern Language** for parsing file formats, a
node-based **Data Processor** for transforming data, an integrated
**disassembler**, **YARA** scanning, hashing, diffing, and a large toolbox of
utilities. It runs on Windows, macOS, Linux, FreeBSD, and even in the browser.

This guide covers everything you do *with* ImHex: installing it, loading data,
editing bytes, writing patterns, running the built-in tools, and driving it from
the command line. Architecture, configuration internals, plugin development, and
deployment live in the companion **Admin Guide**.

> [!NOTE]
> ImHex is free and open source under the GPLv2 license. There is no paid tier,
> no telemetry, and no account requirement. It "will not transfer any
> information to other networked systems unless specifically requested by the
> user."

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Installation](#2-installation)
3. [System Requirements](#3-system-requirements)
4. [The ImHex Interface](#4-the-imhex-interface)
5. [Loading Data: Providers](#5-loading-data-providers)
6. [Working in the Hex Editor](#6-working-in-the-hex-editor)
7. [The Data Inspector](#7-the-data-inspector)
8. [The Pattern Language](#8-the-pattern-language)
9. [Searching Data](#9-searching-data)
10. [Bookmarks, Patches, and Projects](#10-bookmarks-patches-and-projects)
11. [Hashing, Diffing, and Disassembly](#11-hashing-diffing-and-disassembly)
12. [The Data Processor](#12-the-data-processor)
13. [The Tools Collection](#13-the-tools-collection)
14. [YARA Rule Scanning](#14-yara-rule-scanning)
15. [The Content Store](#15-the-content-store)
16. [Workspaces, Layouts, and Themes](#16-workspaces-layouts-and-themes)
17. [Command-Line Interface](#17-command-line-interface)
18. [AI Integration: the MCP Server](#18-ai-integration-the-mcp-server)
19. [Updating ImHex](#19-updating-imhex)
20. [Where ImHex Stores Your Data](#20-where-imhex-stores-your-data)
21. [Troubleshooting](#21-troubleshooting)
22. [Frequently Asked Questions](#22-frequently-asked-questions)
23. [Reference](#23-reference)

---

## 1. Quick Start

The fastest path from zero to inspecting a file:

1. **Install ImHex** for your platform (see [Installation](#2-installation)).
2. **Launch it.** On first launch you'll be offered an interactive tutorial —
   take it; it walks you through the core windows in a few minutes.
3. **Open a file.** Drag a file onto the ImHex window, or use the Welcome
   Screen's *Open File* entry, or `File → Open File`.
4. **Look at your bytes.** The central **Hex editor** shows the raw bytes; the
   **Data Inspector** on the side interprets the bytes under your cursor as many
   different types.
5. **Parse the format.** Open the **Pattern editor**, write (or load) a pattern,
   and ImHex highlights and decodes the file's structures live.

> [!TIP]
> The very first thing most people want is the interactive walkthrough. If you
> dismissed it, you can replay it any time from `Help → Interactive Tutorials`.

A 30-second taste of every major surface, from the command line:

```bash
# Open a file straight into the GUI
imhex path/to/firmware.bin

# Open a file AND apply a pattern to it
imhex --open firmware.bin --pattern firmware.hexpat

# Or skip the GUI entirely — hash a file from the terminal
imhex --hash sha256 firmware.bin
```

```text
sha256(firmware.bin) = 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
```

---

## 2. Installation

The easiest way to install ImHex is to download the latest release from the
[GitHub Releases page](https://github.com/WerWolv/ImHex/releases/latest). A
**NoGPU** build (software-rendered) is available for machines without a GPU or
for VMs without GPU passthrough.

> [!NOTE]
> ImHex ships both an **installed** version (writes config to your user profile)
> and a **portable** version (keeps everything next to the executable). Pick the
> portable build if you want a self-contained, USB-stick-friendly copy.

### Windows

=== "Installer"

    Run the `.msi` installer and follow the prompts. This is the standard,
    auto-updatable installation.

=== "Portable"

    Extract the release `.zip` to any folder and run `imhex-gui.exe` from there.
    Configuration is stored alongside the executable.

=== "Chocolatey"

    ```powershell
    choco install imhex
    ```

=== "Winget"

    ```powershell
    winget install WerWolv.ImHex
    ```

### macOS

Open the drag-and-drop `.dmg` and drag ImHex into `/Applications`.

> [!IMPORTANT]
> The macOS build is **not code-signed**. The first time you launch it, macOS
> may block it — allow it under *System Settings → Privacy & Security*. Release
> binaries target **macOS 15 (Sequoia) or higher**; on older macOS you must
> compile ImHex yourself (see the Admin Guide).

### Linux

ImHex ships official releases for Ubuntu/Debian, Fedora, RHEL/AlmaLinux, and Arch
Linux, plus distro-agnostic AppImage, Flatpak, and Snap packages.

=== "AppImage"

    ```bash
    chmod +x imhex-*.AppImage
    ./imhex-*.AppImage
    ```

=== "Flatpak"

    ```bash
    flatpak install flathub net.werwolv.ImHex
    # or install a downloaded file directly
    flatpak install ./imhex-*.flatpak
    ```

=== "Snap"

    ```bash
    snap install ./imhex-*.snap
    ```

=== "Debian / Ubuntu"

    ```bash
    sudo apt install ./imhex-*.deb
    ```

=== "Fedora / RHEL"

    ```bash
    sudo dnf install ./imhex-*.rpm
    ```

=== "Arch Linux"

    ```bash
    sudo pacman -U imhex-*.pkg.tar.zst
    ```

Distro package managers are also supported (Arch AUR `imhex-bin` / `imhex`,
Fedora `dnf install imhex`, Flathub `net.werwolv.ImHex`).

### Nightly builds

Every commit to the repository produces a fresh build on the
[GitHub Actions page](https://github.com/WerWolv/ImHex/actions?query=workflow%3A%22Build%22).
Nightlies carry the newest features but are not guaranteed stable.

> [!CAUTION]
> Nightly builds can contain regressions that never reach a stable release. Use
> them for testing new features, not for production reverse-engineering work you
> can't afford to lose.

---

## 3. System Requirements

ImHex is a native GUI application that uses your GPU for rendering.

| Component | Requirement |
|-----------|-------------|
| **OS** | Windows 7+ (10/11 recommended); macOS 15+; "modern" Linux; FreeBSD 14.3 (tested) |
| **CPU** | x86, AMD64, or ARM64 officially; any little-endian CPU should work |
| **GPU** | OpenGL 3.0 or higher |
| **RAM** | ~50 MiB baseline; more for complex analysis |
| **Storage** | ~100 MiB |

> [!IMPORTANT]
> ImHex requires a GPU with **OpenGL 3.0** support. If you don't have one, use a
> **NoGPU** (software-rendered) release — it's slower but needs no GPU. If you
> have both an integrated and a dedicated GPU, prefer the dedicated one; some
> Intel HD drivers on Windows are known to produce graphical artifacts.

---

## 4. The ImHex Interface

ImHex is organized into dockable **views** (windows) you can rearrange, detach,
and save into layouts. The main surfaces you'll use:

| View | What it's for |
|------|---------------|
| **Hex editor** | The central byte grid — view and edit raw data |
| **Data Inspector** | Interpret the bytes at the cursor as many data types |
| **Pattern editor** | Write/edit Pattern Language code to parse the file |
| **Pattern Data** | Tree view of the structures your pattern decoded |
| **Data Information** | Entropy, byte distribution, magic/MIME detection |
| **Bookmarks** | Named, colored regions you've marked |
| **Find** / **Replace** | Search and replace across the data |
| **Data Processor** | Node graph for transforming/decoding data |
| **Patches** | The list of byte edits you've made |
| **Highlight Rules** | Custom foreground highlighting rules |
| **Tools** | The utility toolbox (calculators, converters, etc.) |
| **Content Store** | Download patterns, libraries, magic, themes, rules |
| **Theme Manager** | Create and edit color themes |
| **Data Source Settings** | Settings specific to the loaded provider |
| **Command Palette** | Fuzzy command/action launcher |
| **Achievements** | Gamified guide to ImHex features |
| **Interactive Tutorials** | In-app guided walkthroughs |
| **Log Console** | ImHex's internal log output |
| **Settings** | All application settings |
| **Help** | In-app help |

> [!TIP]
> Press the Command Palette shortcut (or `View → Command Palette`) and start
> typing to jump to any action without hunting through menus. It's the fastest
> way to drive ImHex once you know what you want.

### The menu bar and toolbar

The main menu (`File`, `Edit`, `View`, `Help`, plus plugin-contributed menus)
contains every action. The toolbar holds quick-access buttons; you can pin your
favorite menu items to it. Many actions also have keyboard shortcuts, all of
which are listed and **remappable** under `Settings → Shortcuts`.

### Beginner ("Simplified") mode

ImHex offers a simplified mode that hides advanced views, plus extensive
documentation, achievements, and interactive tutorials — so you can grow into
the full feature set instead of being dropped into it.

---

## 5. Loading Data: Providers

ImHex doesn't only open files — it reads from many **data sources**, internally
called *providers*. Each provider exposes a byte range that every other feature
(hex editor, patterns, hashing, etc.) operates on identically.

| Data source | Use it to… |
|-------------|-----------|
| **File** | Open a local file (huge files load efficiently) |
| **Raw Disk** | Read raw disks and partitions |
| **GDB Server** | Read RAM of a running process or embedded device over GDB |
| **Intel Hex** | Load Intel HEX format data |
| **Motorola SREC** | Load Motorola S-record data |
| **Base64** | Decode and view Base64-encoded data |
| **UDP** | Display raw data received over UDP |
| **Process Memory** | Inspect the entire address space of a running process |
| **Remote (SSH/SFTP)** | Load files from remote servers over SSH |
| **Command** | View the output of a command as data |

To open a data source, use the Welcome Screen, `File → Open Other...`, or drag a
file onto the window. Several files can be open at once as separate tabs; switch
between them freely.

> [!NOTE]
> Because everything operates on the provider abstraction, you can write a
> pattern, run YARA rules, hash a region, or run the data processor against
> process memory or a remote file exactly as you would against a local file.

> [!WARNING]
> Reading **raw disks**, **process memory**, and **GDB** targets may require
> elevated privileges and can affect the system you're inspecting. Only attach
> to processes and devices you own or are authorized to analyze.

---

## 6. Working in the Hex Editor

The Hex editor is the heart of ImHex. Bytes are shown in a configurable grid
alongside an ASCII (or custom-encoding) decode column.

### Editing and patching

- **Byte patching** — overwrite bytes directly; every change is tracked.
- **Infinite Undo/Redo** — step backward and forward through all edits.
- **Patch management** — review every edit in the **Patches** view; ImHex can
  export your edits as IPS/IPS32 patch files.

> [!TIP]
> Edits don't have to touch the underlying source. The **Data Processor** lets
> you transform what you *see* (decrypt, decompress, byte-swap) without
> modifying the original bytes — ideal for read-only or in-place analysis.

### Copying data out

Select a region and "Copy bytes as…" into many formats:

- Raw bytes or a hex string
- A C, C++, C#, Rust, Python, Java, or JavaScript array literal
- An ASCII-art hex view
- A self-contained HTML `<div>`

### Navigation

- **Goto** from the start, the end, or the current cursor position.
- Jump to bookmarks, pattern matches, or find results.
- Paged data view for very large sources.

### Display options

The hex editor can render the same bytes many ways:

- Hexadecimal integers (8/16/32/64-bit)
- Signed and unsigned decimal integers (8/16/32/64-bit)
- Floats (16/32/64-bit)
- RGBA8 colors, HexII, or binary
- ASCII and custom encodings — built-in support for UTF-8, UTF-16, Shift-JIS,
  most Windows code pages, and many more

### Highlighting

- **Background highlighting** driven by patterns, find results, and bookmarks.
- **Foreground highlighting** via configurable rules in the **Highlight Rules**
  view — color bytes by value or condition.

---

## 7. The Data Inspector

The **Data Inspector** interprets the bytes starting at your cursor as a long
list of types simultaneously, so you can spot what a field actually is.

Built-in interpretations include:

- Unsigned and signed integers (8, 16, 24, 32, 48, 64-bit)
- Floats (16, 32, 64-bit)
- Signed and unsigned LEB128
- ASCII, wide, and UTF-8 characters and strings
- `time32_t`, `time64_t`, DOS date and time
- GUIDs
- RGBA8 and RGB65 colors

Each row supports endianness toggling and decimal/hex/octal display plus bit
inversion. You can **edit bytes through the inspector** (type a value, it writes
the bytes back), hide rows you don't use, and **add new inspector types** with
the Pattern Language (see [§8](#8-the-pattern-language)).

> [!TIP]
> If you frequently inspect a custom type, write a small inspector script
> instead of decoding by hand every time. Custom inspectors live in the
> `scripts/inspectors` data folder.

---

## 8. The Pattern Language

The **Pattern Language** is ImHex's purpose-built, C++-like language for
describing binary file formats. You write a pattern that defines the structures
in a file; ImHex evaluates it and highlights, decodes, and tabulates the file's
contents live in the **Pattern Data** view.

> [!NOTE]
> The Pattern Language is a separate project with its own full documentation:
> source at [WerWolv/PatternLanguage](https://github.com/WerWolv/PatternLanguage)
> and docs at [docs.werwolv.net/pattern-language](https://docs.werwolv.net/pattern-language/).
> This section covers how you *use* it inside ImHex.

### Writing your first pattern

Open the **Pattern editor** and type a structure, then place it at an address
with the `@` operator:

```rust
struct Header {
    char magic[4];
    u32  version;
    u16  entry_count;
};

Header header @ 0x00;
```

The moment you run it, ImHex highlights bytes `0x00`–`0x09` in the hex editor and
shows the decoded `header` in the Pattern Data tree.

### What the language supports

- Arrays, pointers, structs, unions, enums, bitfields, and namespaces
- Little- and big-endian fields
- Conditionals and control flow
- Syntax highlighting, error marking, and useful error messages in the editor

### Automatic pattern loading

ImHex can pick the right pattern for you automatically based on a file's **MIME
type and magic values** — open a known format and the matching pattern is
applied without manual selection.

### Visualizers

Patterns can attach **visualizers** to data so a field renders as something
meaningful instead of raw bytes:

- Images
- Audio
- 3D models
- Coordinates
- Time stamps

> [!TIP]
> Don't write every pattern from scratch — the official
> [ImHex-Patterns database](https://github.com/WerWolv/ImHex-Patterns) ships
> ready-made patterns, libraries, magic, and constants for many formats. Pull
> them straight into ImHex via the **Content Store** ([§15](#15-the-content-store)).

### Running patterns from the command line

You can drive the standalone Pattern Language tooling without opening the GUI via
the `pl` subcommand (see [§17](#17-command-line-interface)):

```bash
imhex pl --help
```

---

## 9. Searching Data

The **Find** view searches the whole file or just a selection, with several
search modes:

| Mode | Description |
|------|-------------|
| **String** | Find literal strings (with encoding options) |
| **Sequence** | Find a byte/character sequence; optionally case-insensitive |
| **Regex** | Search using regular expressions |
| **Binary Pattern** | Match byte sequences with optional wildcards |
| **Numeric Value** | Find signed/unsigned ints and floats, or value *ranges* |

For strings you can set a **minimum length**, restrict the **character set**
(lower/upper/digits/symbols), and choose an **encoding** (ASCII, UTF-8, UTF-16
big/little-endian). Numeric searches let you specify size, endianness, and
whether to skip unaligned values.

Matches are highlighted in the hex editor and you can jump between them. The
**Replace** view performs find-and-replace.

> [!NOTE]
> A common request — "Raw Find → Regex" — is already covered: choose the
> **Regex** search mode in the Find view to search text using regular
> expressions.

---

## 10. Bookmarks, Patches, and Projects

### Bookmarks

Mark regions of interest with names, colors, and comments. Bookmarked regions are
highlighted in the hex editor, you can jump to them, and you can open a
bookmark's content in its own tab.

### Patches

Every byte you edit is recorded as a patch. The **Patches** view lists them, and
ImHex can export them as **IPS** or **IPS32** patch files for sharing or
re-applying.

### Project files

A **project** (`.hexproj`) bundles your loaded data sources, bookmarks, patterns,
patches, and layout into a single file so you can resume an analysis exactly
where you left off.

- Save with `File → Save Project` / `Save Project As`.
- Open a project to restore all of its providers and per-provider data.

> [!IMPORTANT]
> ImHex automatically writes a **crash backup** project if it crashes while you
> have data open, so you rarely lose work. After a crash, look for
> `crash_backup.hexproj` in your config folder (see [§20](#20-where-imhex-stores-your-data)).

---

## 11. Hashing, Diffing, and Disassembly

### Hashing

The **Hashes** plugin computes a wide range of algorithms over the whole file, a
specific region, or an arbitrary string. Supported algorithms include CRC8/16/32
(with custom initial values and polynomials), MD5, the SHA-1/SHA-2 family,
Adler32, the SMHasher family (Murmur, xxHash, SipHash, etc.), Tiger/Tiger2,
Blake2B/Blake2S, and many classic string hashes. See the full list in
[§23 Reference](#23-reference).

You can also hash a file straight from the terminal:

```bash
imhex --hash md5 document.pdf
```

```text
md5(document.pdf) = 1a79a4d60de6718e8e5b326e338ae533
```

### Diffing

The **Diffing** plugin compares two data sources side by side, highlighting
differences and listing them in a table view. It uses an edit-distance algorithm
for sequence comparison.

### Disassembly

The integrated **Disassembler** (powered by Capstone) supports a large set of
architectures, including ARM32/ARM64, MIPS, x86 (16/32/64-bit), PowerPC, SPARC,
SystemZ, RISC-V, WebAssembly, and more (full list in [§23](#23-reference)).
Select a region, choose the architecture, and ImHex disassembles it. You can even
write custom disassemblers for your own architectures.

---

## 12. The Data Processor

The **Data Processor** is a node-based, visual pipeline for transforming data
*before* it's displayed in the hex editor — without altering the source bytes.

- Drag nodes onto the canvas and wire them together.
- Decrypt, decode, decompress, or otherwise modify the data stream.
- The transformed result feeds the hex editor and other views.
- Add your own custom nodes (downloadable from the Content Store, or scripted).

Typical uses: decrypt an encrypted blob and view the plaintext, decompress an
embedded archive, or de-XOR an obfuscated section — all reversibly and
non-destructively.

---

## 13. The Tools Collection

The **Tools** view is a grab-bag of standalone utilities. Each is a self-contained
panel:

| Tool | What it does |
|------|--------------|
| **ASCII table** | Reference table of ASCII characters |
| **Base converter** | Convert numbers between bases |
| **Byte Swapper** | Swap byte order of a value |
| **Calculator** | Mathematical expression evaluator |
| **Graphing Calculator** | Plot mathematical functions |
| **Color picker** | Pick colors in many formats |
| **LLVM Demangler** | Demangle Itanium/MSVC/Rust/D-Lang symbols |
| **Euclidean Algorithm** | Compute GCD step by step |
| **Division by invariant Multiplication** | Reverse compiler division tricks |
| **UNIX Permissions Calculator** | Build/parse `chmod` permission bits |
| **Regex replacer** | Test regex find/replace |
| **Wikipedia term definitions** | Look up terms inline |
| **File Tools** | Split, combine, and shred files |
| **File Uploader** | Upload a file |
| **HTTP Requests** | Make HTTP requests |
| **TCP Client/Server** | Send/receive over TCP |

Several of these are also exposed as command-line subcommands (calculator,
demangler — see [§17](#17-command-line-interface)).

> [!CAUTION]
> **File shredder** in *File Tools* permanently destroys data by overwriting it.
> There is no undo for a shredded file. Double-check the target before running it.

---

## 14. YARA Rule Scanning

The **YARA** plugin scans the loaded data with [YARA](https://github.com/VirusTotal/yara)
rules to identify patterns, malware signatures, or structures.

- Apply one or many rules at once.
- Matches are highlighted in the hex editor.
- Jump directly to each match.
- Download official rule sets through the Content Store.

> [!NOTE]
> YARA rules and the "advanced analysis" rule set are stored under the `yara`
> data folder (see [§20](#20-where-imhex-stores-your-data)). Drop your own
> `.yar` files there to make them available.

---

## 15. The Content Store

The **Content Store** is ImHex's built-in downloader for community content,
pulled from the
[ImHex-Patterns database](https://github.com/WerWolv/ImHex-Patterns):

- Pattern files for decoding file formats
- Libraries for the Pattern Language
- Magic files for file-type detection
- Custom Data Processor nodes
- Custom encodings
- Custom themes
- YARA rules

Browse, download, update, and remove items from within ImHex. Downloaded content
lands in the appropriate data folder automatically.

> [!TIP]
> If you're analyzing a common format (PNG, ELF, PE, ZIP, …), check the Content
> Store first — odds are there's already a maintained pattern that decodes it
> completely.

---

## 16. Workspaces, Layouts, and Themes

### Layouts

A **layout** is an arrangement of views. Rearrange windows, dock and detach them,
then save the arrangement as a named layout (`View` menu). You can lock the
current layout so it can't be changed accidentally.

### Workspaces

A **workspace** groups a layout with state into a switchable working set. Create,
switch, import, and export workspaces to move your setup between machines.

### Themes

ImHex is dark by default (your retinas will thank you) but ships a light mode and
fully customizable themes:

- Edit colors and styles for every UI element in the **Theme Manager**.
- Export and share theme files; import others' themes.
- Set a custom accent color.
- Use custom fonts.

> [!TIP]
> Themes, layouts, and workspaces are all plain files in your data folders
> ([§20](#20-where-imhex-stores-your-data)) — back them up or sync them across
> machines by copying those folders.

---

## 17. Command-Line Interface

ImHex is a GUI application that also exposes a rich command line. Run a subcommand
with `--long` or its `-short` form. With no subcommand, files you pass are opened
(the `open` command is the default).

> [!NOTE]
> On Windows, a small **forwarder** executable handles the console so launching
> ImHex from Explorer doesn't leave a stray console window, while launching from
> a terminal still gives you colored output. You don't need to do anything — it's
> automatic.

List everything with `imhex --help`. The full subcommand set:

| Long | Short | Description |
|------|:-----:|-------------|
| `--help` | `-h` | Print help about ImHex |
| `--version` | | Print full ImHex version (with logo) |
| `--version-short` | | Print only the version string |
| `--plugins` | | List installed plugins (or add plugin load paths) |
| `--language` | | Change the language ImHex uses |
| `--verbose` | `-v` | Enable verbose debug logging |
| `--open` | `-o` | Open the files passed as arguments **(default)** |
| `--new` | `-n` | Create a new empty file |
| `--select` | `-s` | Select a byte range in the Hex Editor |
| `--pattern` | `-p` | Set the loaded pattern (source or file path) |
| `--calc` | | Evaluate a mathematical expression |
| `--hash` | | Calculate a file's hash |
| `--encode` | | Encode a string (base64 or hex) |
| `--decode` | | Decode a string (base64 or hex) |
| `--magic` | | Identify a file's type (`mime` or `desc`) |
| `--pl` | | Interact with the Pattern Language CLI |
| `--hexdump` | | Print a hex dump of a file |
| `--demangle` | | Demangle a mangled symbol |
| `--reset-settings` | | Reset all settings to default (asks to confirm) |
| `--debug-mode` | | Enable debugging features |
| `--validate-plugin` | | Check that a plugin can be loaded |
| `--save-editor` | | Open a save-file editor (`file` or `gist`) |
| `--file-info` | `-i` | Display information about a file |
| `--mcp` | | Start an MCP server for AI tools ([§18](#18-ai-integration-the-mcp-server)) |

### Examples

**Open files and pre-select a region:**

```bash
imhex --open dump.bin --select 0x100 0x1FF
```

**Apply a pattern (inline source *or* a file path):**

```bash
imhex --open game.sav --pattern save_format.hexpat
```

**Hash a file** (algorithms: `md5`, `sha1`, `sha224`, `sha256`, `sha384`, `sha512`):

```bash
imhex --hash sha1 installer.exe
```

```text
sha1(installer.exe) = 2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
```

**Encode / decode** (algorithms: `base64`, `hex`):

```bash
imhex --encode base64 "hello world"
```

```text
encode_base64(hello world) = aGVsbG8gd29ybGQ=
```

**Identify a file type** (`mime` or `desc`):

```bash
imhex --magic mime photo.unknown
```

```text
image/png
```

**Hex-dump a file region** — `imhex --hexdump <file> [offset] [size]`:

```bash
imhex --hexdump header.bin 0x00 0x20
```

**Evaluate an expression:**

```bash
imhex --calc "5 * 7"
```

```text
35
```

**Demangle a symbol:**

```bash
imhex --demangle "_ZN3hex4initL7runImHexEv"
```

> [!WARNING]
> `imhex --reset-settings` erases **all** of your settings. It requires you to
> type a confirmation string (`YES I AM ABSOLUTELY SURE`) before proceeding —
> there is no undo.

---

## 18. AI Integration: the MCP Server

ImHex includes an **MCP (Model Context Protocol) server** so AI assistants can
interact with ImHex programmatically. Start it from the command line:

```bash
imhex --mcp
```

This runs an MCP **client** bridge over standard input/output (the kind of
transport AI tooling expects), connecting to ImHex's internal MCP server. The
server speaks JSON-RPC 2.0 and implements the MCP `2025-06-18` protocol,
exposing ImHex "tools" that an AI can call.

> [!NOTE]
> The MCP server listens only on a fixed **internal loopback port (19743)** for
> the local bridge — it is not a remote network service. Configuration of AI
> clients to use this bridge is covered in the Admin Guide.

---

## 19. Updating ImHex

How you update depends on how you installed ImHex:

- **Installer / package builds** can update in place. ImHex's bundled updater
  downloads the correct artifact for your platform and architecture and runs the
  appropriate installer (`.msi` on Windows, `.dmg` on macOS, `.deb`/`.rpm`/
  `.pkg.tar.zst`/AppImage/Flatpak/Snap on Linux).
- **Portable builds** are updated by downloading and extracting a new release.
- **Distro package managers** update through their normal channels
  (`apt`, `dnf`, `pacman`, `flatpak`, …).

> [!NOTE]
> ImHex checks for both **stable** and **nightly** update channels. If the
> updater can't update your particular install type, it opens the latest release
> page in your browser so you can update manually.

> [!IMPORTANT]
> The Linux package updaters use `zenity` to prompt for your password and `sudo`
> to install. If you installed via a package manager, prefer updating through
> that manager instead of the in-app updater.

---

## 20. Where ImHex Stores Your Data

ImHex keeps configuration and content in standard per-OS locations. The exact
base directory depends on your platform and whether you run the **portable** or
**installed** build.

| Platform | Base location |
|----------|---------------|
| **Windows (installed)** | `%LOCALAPPDATA%\imhex` |
| **Windows (portable)** | next to `imhex-gui.exe` |
| **macOS** | `~/Library/Application Support/imhex` |
| **Linux** | XDG dirs — config in `~/.config/imhex`, data in `~/.local/share/imhex` (+ system data dirs) |

Within the base, ImHex uses these subfolders:

| Folder | Contents |
|--------|----------|
| `config` | Settings (`settings.json`), achievements, crash info |
| `recent` | Recently opened files list |
| `updates` | Downloaded update artifacts |
| `plugins` / `lib` | Plugins and libraries |
| `patterns` / `includes` | Pattern files and pattern include libraries |
| `magic` | Magic databases for file-type detection |
| `yara` / `yara/advanced_analysis` | YARA rules |
| `backups` | Project/data backups |
| `constants` | Constant definitions |
| `encodings` | Custom text encodings |
| `themes` | Theme files |
| `layouts` / `workspaces` | Saved layouts and workspaces |
| `scripts` / `scripts/inspectors` / `scripts/nodes` | Custom scripts, inspectors, nodes |
| `disassemblers` | Custom disassembler definitions |
| `logs` | Log files |

> [!TIP]
> To migrate ImHex to a new machine, copy these folders. To start completely
> fresh, you can delete `config` (or run `imhex --reset-settings`).

---

## 21. Troubleshooting

Format below: the symptom, the cause, the fix, and how to avoid it.

### ImHex won't start, or the window is black / full of artifacts

**Cause:** Missing or buggy OpenGL 3.0 support, common with some integrated Intel
HD GPU drivers on Windows or inside VMs without GPU passthrough.

**Solution:** Download and run the **NoGPU** (software-rendered) release. If you
have a dedicated GPU, force ImHex to use it in your GPU control panel.

**Prevention:** Keep GPU drivers updated; prefer the dedicated GPU.

### Error: `Failed to resolve import std/core` (Web/WASM)

**Cause:** The Pattern Language standard library includes aren't reachable in the
WebAssembly build's include paths.

**Solution:** Make sure pattern include libraries are present (download them via
the Content Store). On the native desktop build, includes resolve from the
`includes` data folder automatically.

**Prevention:** Install the pattern standard library from the Content Store before
running patterns that `import std/...`.

### Opening a file from the command line gives an empty layout

**Cause:** A known interaction where launching with a file argument can start with
a blank layout.

**Solution:** Open the file from within ImHex (`File → Open File`) or reset your
layout from the `View` menu. Ensure you're on the latest release.

**Prevention:** Save a known-good workspace and switch to it after launch.

### Default folders (patterns, magic, etc.) don't exist

**Cause:** On a brand-new install, some default data directories aren't created
until first needed.

**Solution:** Download any item from the **Content Store** — ImHex creates the
target folders on demand. Or create the folders listed in [§20](#20-where-imhex-stores-your-data)
manually.

**Prevention:** Run the first-launch tutorial and pull a pattern from the store
early.

### A hash result changes / breaks after restarting ImHex

**Cause:** Custom hash configuration (e.g. a CRC's initial value or polynomial)
that isn't being persisted as expected.

**Solution:** Re-enter the custom hash parameters after restart, or compute the
hash from the command line (`imhex --hash ...`) where parameters are explicit.

**Prevention:** For repeatable hashing in scripts, prefer the CLI.

### Scaling / DPI looks wrong

**Cause:** A mismatch between ImHex's scale setting and your display's DPI.

**Solution:** Set the UI scale manually in `Settings → Interface`.

**Prevention:** Set an explicit scale rather than relying on auto-detection on
multi-monitor mixed-DPI setups.

### My keyboard shortcut does nothing while typing/editing

**Cause:** Most global shortcuts are suppressed while you're typing in a text
field (by design), unless the shortcut is flagged to work while typing.

**Solution:** Click outside the text field, then trigger the shortcut — or remap
it under `Settings → Shortcuts`.

**Prevention:** Learn which actions are global vs. view-local; the Shortcuts
settings page shows both.

### ImHex asks to confirm exit even with no changes

**Cause:** A known issue where the exit-confirmation prompt can appear without
unsaved changes.

**Solution:** Confirm the exit; no data is at risk. Update to the latest release
where exit handling is improved.

### Files from a network share load as zero bytes

**Cause:** Certain network filesystems (e.g. GVFS SMB mounts) report sizes in a
way that can truncate reads.

**Solution:** Copy the file locally first, then open the local copy.

**Prevention:** Work from local copies when analyzing files on network mounts.

### Where are the logs?

ImHex writes logs to the `logs` data folder. Enable verbose logging with
`imhex --verbose` (or `-v`) when reproducing an issue, and include the log when
reporting a bug.

> [!TIP]
> When something crashes, ImHex writes a `crash.json` (pointing at the log and
> the crash-backup project) into your `config` folder. Attach both to any bug
> report.

---

## 22. Frequently Asked Questions

**Q: Is ImHex free? Is there a catch?**
Yes, it's free and open source (GPLv2). No telemetry, no account. It only talks
to the network when you ask it to (updates, Content Store, HTTP tool, etc.).

**Q: Do I need a GPU?**
ImHex normally needs OpenGL 3.0. If you don't have a usable GPU, use a **NoGPU**
release, which is software-rendered (slower, but works anywhere).

**Q: What's the difference between the portable and installed versions?**
The installed version stores config in your user profile and can auto-update in
place. The portable version keeps everything next to the executable — great for
USB sticks and locked-down machines.

**Q: Can I edit a file without changing the original bytes?**
Yes. Use the **Data Processor** to transform what you see non-destructively, or
work in a project and export your edits as IPS patches instead of overwriting.

**Q: How do I parse a specific file format?**
Write a **pattern** in the Pattern Language, or download a ready-made one from
the **Content Store**. ImHex can also auto-load a pattern based on the file's
magic/MIME type.

**Q: Can ImHex open something other than files?**
Yes — raw disks, process memory, GDB targets, UDP streams, Intel HEX, Motorola
SREC, Base64, remote files over SSH/SFTP, and command output. See
[§5](#5-loading-data-providers).

**Q: Can I script or automate ImHex?**
For batch work, use the command-line subcommands ([§17](#17-command-line-interface))
— hashing, encoding/decoding, magic detection, hex dumps, demangling, and the
Pattern Language CLI all run headless. Custom scripts, nodes, and inspectors
extend the GUI.

**Q: How do AI tools talk to ImHex?**
Run `imhex --mcp` to bridge an MCP-speaking AI client to ImHex's internal MCP
server ([§18](#18-ai-integration-the-mcp-server)).

**Q: Which architectures can the disassembler handle?**
Everything Capstone supports — ARM32/64, MIPS, x86 (16/32/64), PowerPC, SPARC,
SystemZ, RISC-V, WebAssembly, and more. Full list in [§23](#23-reference).

**Q: How do I change the language / theme / shortcuts?**
All in `Settings`: language and scaling under *Interface*, themes via the *Theme
Manager*, key bindings under *Shortcuts*.

**Q: Where can I get more patterns and example files?**
The [ImHex-Patterns repository](https://github.com/WerWolv/ImHex-Patterns) — and
you can PR your own. Most of it is installable directly through the Content Store.

**Q: How do I report a bug?**
Open an issue on [GitHub](https://github.com/WerWolv/ImHex/issues) (or join the
Discord). Include your OS, ImHex version (`imhex --version-short`), steps to
reproduce, and the log file (run with `-v`).

**Q: Is there full documentation for the Pattern Language?**
Yes: [docs.werwolv.net/pattern-language](https://docs.werwolv.net/pattern-language/).

---

## 23. Reference

### Supported hash algorithms

CRC8, CRC16, CRC32 (custom initial values and polynomials, with many default
polynomials); MD5; SHA-1, SHA-224, SHA-256, SHA-384, SHA-512; Adler32; AP; BKDR;
Bernstein, Bernstein1; DEK, DJB, ELF, FNV1, FNV1a, JS, PJW, RS, SDBM; OneAtTime,
Rotating, ShiftAndXor, SuperFast; Murmur2_32, MurmurHash3_x86_32,
MurmurHash3_x86_128, MurmurHash3_x64_128; SipHash64, SipHash128; XXHash32,
XXHash64; Tiger, Tiger2; Blake2B, Blake2S.

> CLI `--hash` supports a subset: `md5`, `sha1`, `sha224`, `sha256`, `sha384`,
> `sha512`.

### Disassembler architectures (via Capstone)

ARM32 (ARM, Thumb, Cortex-M, AArch32), ARM64, MIPS (MIPS32, MIPS64, MIPS32R6,
Micro), x86 (16/32/64-bit), PowerPC (32/64-bit), SPARC, IBM SystemZ, xCORE, M68K,
TMS320C64X, M680X, Ethereum, RISC-V, WebAssembly, MOS65XX, Berkeley Packet
Filter. Custom disassemblers are also supported.

### Import / export formats

Import/export: Base64 files, IPS and IPS32 patches, Markdown reports, and binary
arrays for various programming languages.

### Settings categories

`Settings` is organized into: **General**, **Interface**, **Hex Editor**,
**Pattern Editor**, **Folders**, **Proxy**, **Toolbar**, **Shortcuts**,
**Plugins** (and *Plugins to be loaded*), and **Experiments**. See the Admin
Guide for a deep configuration reference.

### Command-line quick reference

| Command | Usage |
|---------|-------|
| Open | `imhex [--open] <files...>` |
| New file | `imhex --new` |
| Select range | `imhex --select <start> [<end>]` |
| Apply pattern | `imhex --pattern <source-or-file>` |
| Hash | `imhex --hash <md5\|sha1\|sha224\|sha256\|sha384\|sha512> <file>` |
| Encode | `imhex --encode <base64\|hex> <string>` |
| Decode | `imhex --decode <base64\|hex> <string>` |
| Magic | `imhex --magic <mime\|desc> <file>` |
| Hex dump | `imhex --hexdump <file> [offset] [size]` |
| Calculator | `imhex --calc <expression>` |
| Demangle | `imhex --demangle <symbol>` |
| Pattern Language CLI | `imhex pl [args...]` |
| Save editor | `imhex --save-editor [file\|gist] <path-or-id>` |
| File info | `imhex --file-info <file>` |
| MCP server | `imhex --mcp` |
| Reset settings | `imhex --reset-settings` |

### Useful links

- Website: <https://imhex.werwolv.net>
- Documentation: <https://docs.werwolv.net>
- Web version: <https://web.imhex.werwolv.net>
- Pattern Language: <https://github.com/WerWolv/PatternLanguage> · <https://docs.werwolv.net/pattern-language/>
- Pattern/format database: <https://github.com/WerWolv/ImHex-Patterns>
- Plugin template: <https://github.com/WerWolv/ImHex-Plugin-Template>
- Discord: <https://discord.gg/X63jZ36xBY>

---

_Generated June 2026 from WerWolv/ImHex at 8a6be85. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._