How to Configure Dear ImGui at Compile-Time Using imconfig.h

Dear ImGui's compile-time behavior is controlled entirely through preprocessor macros defined in imconfig.h, which is automatically included by imgui.h to ensure every translation unit uses identical settings.

Dear ImGui (ocornut/imgui) centralizes its build-time customization through a single configuration header. When you configure Dear ImGui at compile-time using imconfig.h, you control data structure layouts, API visibility, and optional features before compilation begins. This mechanism guarantees that both your application code and the library implementation see the same defines, preventing ABI mismatches across your project.

How imconfig.h Works

The configuration system relies on the C preprocessor to inject settings before any ImGui code is parsed. In imgui.h, the very first substantive action is #include "imconfig.h", meaning every translation unit that consumes ImGui headers automatically absorbs your compile-time definitions.

According to the source code in imconfig.h (lines 9-13), this design ensures that data-structure layouts and feature sets remain consistent across the entire program. Because all ImGui source files—including imgui.cpp, imgui_widgets.cpp, and imgui_draw.cpp—also include imgui.h, they automatically pick up the same macros. This consistency is critical; mismatched defines between headers and compiled objects can cause memory corruption or linkage errors.

Providing Your Configuration File

You have two supported methods to supply your configuration:

1. Edit the template directly – Modify the imconfig.h file that ships with the repository. This is the quickest way to start but requires merging changes when updating ImGui.
2. Use a custom header – Define IMGUI_USER_CONFIG "my_imgui_config.h" before including any ImGui headers. As noted in imconfig.h (lines 6-8), this keeps the original repository untouched, making future updates seamless.

When using the second approach, ensure IMGUI_USER_CONFIG is defined identically in every translation unit that includes ImGui headers.

Verifying Header-Library Consistency

After creating an ImGui context with ImGui::CreateContext(), call IMGUI_CHECKVERSION() in one of your source files. As documented in imconfig.h (lines 12-13), this macro performs a compile-time check that the headers and compiled library were built with matching configuration defines. Omitting this check may result in subtle runtime bugs if different translation units see different macros.

Common Compile-Time Configuration Options

The template imconfig.h (lines 34-74) contains a comprehensive list of available macros. Here are the most frequently used options:

• IMGUI_DISABLE_DEMO_WINDOWS – Strips out ImGui::ShowDemoWindow() and ShowStyleEditor(), reducing binary size for release builds.
• IMGUI_DISABLE_DEBUG_TOOLS – Removes metrics and debug windows such as ShowMetricsWindow() and ShowDebugLogWindow() from production builds.
• IMGUI_DISABLE_DEFAULT_FONT – Excludes the built-in Proggy fonts when you supply your own font atlas.
• IMGUI_USE_WCHAR32 – Switches ImWchar from 16-bit to 32-bit, enabling Unicode planes 1-16 for emoji and high-code-point glyphs.
• IMGUI_ENABLE_FREETYPE – Switches font rasterization from the bundled stb_truetype to FreeType for higher-quality rendering or SVG font support.
• IMGUI_DEFINE_MATH_OPERATORS – Adds implicit conversion operators between your math types and ImVec2/ImVec4, enabling seamless integration with custom math libraries.
• IMGUI_API – Allows exporting ImGui symbols from a DLL using __declspec(dllexport)/dllimport when building ImGui as a shared library on Windows.

Implementation Examples

Editing the Shipped Template

For quick prototyping, edit the repository's imconfig.h directly:

// imconfig.h – edit the template directly
#define IMGUI_DISABLE_DEMO_WINDOWS            // Remove demo windows
#define IMGUI_DISABLE_DEBUG_TOOLS             // Strip debug tools
#define IMGUI_USE_WCHAR32                     // Enable full Unicode support
#define IMGUI_ENABLE_FREETYPE                 // Use FreeType for fonts

Using a Custom Configuration File

For production projects, create a separate header to avoid merge conflicts during updates:

// my_imgui_config.h  (placed anywhere in your project)
#define IMGUI_DISABLE_DEMO_WINDOWS
#define IMGUI_DISABLE_DEBUG_TOOLS
#define IMGUI_USE_WCHAR32
#define IMGUI_ENABLE_FREETYPE

// In *one* source file *before* any ImGui includes
#define IMGUI_USER_CONFIG "my_imgui_config.h"

#include "imgui.h"          // <-- pulls my_imgui_config.h automatically
#include "imgui_impl_sdl.h"
#include "imgui_impl_opengl3.h"

int main()
{
    ImGui::CreateContext();
    IMGUI_CHECKVERSION();   // Verifies that the compiled headers match the library
    // …
}

Replacing the Default Allocator

Advanced users can override memory allocation:

// my_imgui_config.h
#define IMGUI_DISABLE_DEFAULT_ALLOCATORS   // Prevent ImGui from using malloc/free

// In one of your .cpp files
#include "imgui.h"

static void* MyAlloc(size_t sz, void* user_data) { return my_custom_alloc(sz); }
static void  MyFree(void* ptr, void* user_data) { my_custom_free(ptr); }

int main()
{
    ImGui::SetAllocatorFunctions(MyAlloc, MyFree, nullptr);
    ImGui::CreateContext();
    // …
}

Summary

• Centralized configuration – All compile-time settings live in imconfig.h, included automatically by imgui.h.
• Two setup methods – Edit the shipped template for quick tests, or use IMGUI_USER_CONFIG for production code to maintain update compatibility.
• Cross-unit consistency – Every .cpp file including imgui.h sees the same macros, ensuring ABI stability across your project.
• Validation – Always call IMGUI_CHECKVERSION() after ImGui::CreateContext() to verify header-library alignment.
• Common options – Disable demo windows, switch to FreeType, enable 32-bit Unicode, or replace allocators using simple #define statements.

Frequently Asked Questions

Can I configure Dear ImGui without modifying the original repository files?

Yes. Define IMGUI_USER_CONFIG "your_config.h" before any ImGui includes. According to imconfig.h (lines 6-8), this macro tells imgui.h to include your custom file instead of the default template, keeping the upstream repository pristine and simplifying future updates.

What happens if my headers and compiled library have different configurations?

Undefined behavior and potential memory corruption can occur. Dear ImGui uses compile-time macros to determine data structure sizes and member layouts. If your application sees different defines than the compiled imgui.cpp, offsets and sizes will mismatch. Always use IMGUI_CHECKVERSION() after creating the context to catch these discrepancies.

How do I enable FreeType font rendering in Dear ImGui?

Define IMGUI_ENABLE_FREETYPE in your imconfig.h before building the library. This switches the font rasterizer from stb_truetype to FreeType, enabling higher-quality glyph rendering and support for advanced font features. You must link against the FreeType library in your build system when using this option.

Is it safe to change imconfig.h after ImGui has been compiled?

No. Because macros affect data structure layouts—such as ImDrawVert size when using IMGUI_USE_WCHAR32 or custom vertex formats—changing imconfig.h requires recompiling the entire ImGui library and all code that includes imgui.h. Mixing object files compiled with different configurations will result in ABI mismatches.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}