How do I embed a binary file in C++ using incbin?

Include incbin.h and use the INCBIN macro with a name and file path, e.g., INCBIN(Icon, 'icon.png'); this creates static arrays for data, end, and size that are linked into the executable.

incbin vs using xxd or objcopy for binary inclusion?

incbin is compiler-agnostic and doesn't require external tools for most compilers, while xxd or objcopy are toolchain-specific and may need extra build steps or linker scripts.

Does incbin work with Visual Studio projects?

Yes, but for MSVC, you must use the provided tool as a pre-build step to process INCBIN macros, and features like INCTXT or custom types are not yet supported, adding setup complexity.

How to reference embedded data in multiple source files?

Use INCBIN_EXTERN or INCTXT_EXTERN in other translation units to declare the symbols, and in C++, wrap them in extern 'C' to prevent name mangling, enabling cross-unit access.

Can incbin handle large files like videos?

Technically yes, but it will significantly increase executable size; incbin is best for smaller assets like icons, shaders, or config files where size impact is manageable.

How to change the symbol prefix from 'g' in incbin?

Define INCBIN_PREFIX before including incbin.h, e.g., #define INCBIN_PREFIX my_, to customize symbol names, and combine with INCBIN_STYLE for full control over naming conventions.

Open-Awesome

Incbin

UnlicenseC

A single-header C/C++ library for embedding binary and text files directly into executables using compiler inline assembly.

GitHub

1.2k stars107 forks0 contributors

What is Incbin?

incbin is a single-header C/C++ library that allows developers to embed binary files (like images, audio, or text) directly into their executables at compile time. It solves the problem of managing external asset dependencies by converting files into static arrays that are linked into the program, making deployment simpler and improving runtime performance by eliminating file I/O.

Target Audience

C/C++ developers working on embedded systems, game development, or applications where bundling assets with the executable is required, especially those targeting multiple compilers and platforms.

Value Proposition

Developers choose incbin for its extreme portability across compilers, zero runtime overhead, and flexibility in symbol naming and alignment—all without external dependencies, unlike heavier asset management libraries.

Overview

Include binary files in C/C++

Use Cases

Best For

Embedding icons, fonts, or images in GUI applications
Including shader files or configuration data in game engines
Bundling assets for embedded systems without a filesystem
Creating single-executable tools with built-in resources
Ensuring cross-compiler compatibility for binary inclusion
Reducing deployment complexity by eliminating external asset files

Not Ideal For

Projects requiring dynamic asset loading from network or filesystem at runtime
Teams using only MSVC without integrating the preprocessing tool into build steps
Applications where minimizing executable size is critical and assets are large or numerous

Pros & Cons

Pros

Extreme Compiler Portability

Works with GCC, Clang, MSVC (via tool), and over 15 other compilers, making it ideal for cross-platform projects without vendor lock-in.

Zero Runtime Overhead

Embeds data directly into the executable at compile time, eliminating file I/O and external dependencies for faster asset access.

Flexible Symbol Customization

Allows prefix and style changes via INCBIN_PREFIX and INCBIN_STYLE macros to match existing coding conventions and naming schemes.

Automatic SIMD Alignment

Detects SIMD extensions and aligns data appropriately (e.g., 16 bytes for SSE, 32 for AVX), optimizing for vectorized code use cases.

Cons

MSVC Tool Complexity

MSVC support requires a separate preprocessing tool and integration into pre-build events, and it currently lacks INCTXT and custom type support.

Executable Size Bloat

Embedding large binary files directly increases executable size, which can be problematic for memory-constrained embedded systems or deployment.

Manual String Handling

INCTXT adds a NUL-terminator, but the size symbol includes it, requiring developers to subtract one for accurate string length, introducing potential errors.

Frequently Asked Questions

Related Projects

ProtoBuf

Protocol Buffers - Google's data interchange format

Stars71,169

Forks16,117

Last commit6 hours ago

C/C++

A curated list of awesome C++ (or C) frameworks, libraries, resources, and shiny things. Inspired by awesome-... stuff.

Stars70,988

Forks8,272

Last commit9 hours ago

JSON for Modern C++

Stars49,519

Forks7,380

Last commit4 days ago

Blazor

ASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.

Stars37,872

Forks10,633