Pull the bytes of a file into the program at compile time, as a comma-separated list of integers. Directive:
#embed· Test:__has_embed,__cpp_pp_embed(202502L) · Since: C++26 (C23 in C)
logo.png on disk: 89 50 4E 47 0D 0A 1A 0A ...
constexpr unsigned char logo[] = {
#embed "logo.png" --> 137, 80, 78, 71, 13, 10, 26, 10, ...
};
#embed is #include for data: the preprocessor replaces the directive with
one int integer literal per byte (strictly, per CHAR_BIT bits) of the
resource. It replaces xxd -i scripts and linker tricks, and compilers can
implement it without materialising millions of tokens, so it's fast for large
files.
#embed "resource" parameters... quote form: searched like "header", then like <resource>
#embed <resource> parameters... bracket form: implementation-defined search paths
(GCC/Clang: --embed-dir=<dir>, -I is not used)
| Parameter | Effect |
|---|---|
limit(n) |
at most n elements (a #if-style constant expression ≥ 0) |
offset(n) |
skip the first n elements (≥ 0) — C++29, see below |
prefix(tokens) |
placed before the list — only if the resource isn't empty |
suffix(tokens) |
placed after the list — only if the resource isn't empty |
if_empty(tokens) |
replaces the whole directive only if the resource is empty |
Each may appear at most once. A resource is empty when the count after
offset and limit is zero, so limit(0) always makes it empty.
C++26 (N5050) and C23 standardise limit, prefix, suffix and if_empty.
The plain offset parameter was added for C++29 by
P3540R3 (it's in the current working draft at
eel.is) and no local compiler accepts it yet — GCC 15/16: "unknown embed
parameter 'offset'"; Clang 22: "unknown embed preprocessor parameter
'offset'". What works today is the vendor spelling it standardises: GCC's
gnu::offset and Clang's clang::offset. An unsupported parameter makes
__has_embed return 0, so you can test for it.
__has_embed(resource params…) is usable in #if and evaluates to:
| Macro | Value | Meaning |
|---|---|---|
__STDC_EMBED_NOT_FOUND__ |
0 |
not found, or a parameter isn't supported |
__STDC_EMBED_FOUND__ |
1 |
found and not empty |
__STDC_EMBED_EMPTY__ |
2 |
found but empty (after offset/limit) |
A missing resource in #embed itself is ill-formed (a hard error).
| Compiler | -std=c++26 |
-std=c++26 -pedantic-errors |
__cpp_pp_embed |
standard offset (C++29) |
|---|---|---|---|---|
| GCC 15.2 | ✅ | ✅ | 202502L |
❌ (gnu::offset ✅) |
| GCC 16.2 | ✅ | ✅ | 202502L |
❌ (gnu::offset ✅) |
| Clang 22.1 | ✅ with a warning: "#embed is a Clang extension" (-Wc23-extensions) |
❌ the warning becomes an error | not defined | ❌ (clang::offset ✅) |
All three produce the same values, honour the four C++26 parameters, and give
__has_embed the values above. Clang implements #embed for C23 and accepts it in C++ as an
extension, but doesn't yet claim the C++26 feature — so test __has_embed/__cpp_pp_embed rather than the standard
version, and expect -pedantic-errors builds on Clang to reject it.
Older toolchains, from the platform runs: GCC 13
and 14 have no #embed at all (no __has_embed, and __cpp_pp_embed isn't
defined, so use it only inside #ifdef). Clang 19 and 20 (and Apple Clang 17,
which is LLVM 19) have #embed, but deducing std::initializer_list from a
braced list that holds one (auto il = { #embed "f" };) fails with "excess
elements in array initializer"
(llvm/llvm-project#122306,
fixed in Clang 21); arrays are fine.
- Shaders, fonts, images, certificates, test vectors, lookup tables — any data
you want inside the binary and available in
constexpr. - Instead of generated
.incfiles (xxd -i),objcopy/ld -b binarysymbols, orincbinassembler tricks:#embedis portable, sizes are known at compile time, and build systems can track the dependency. - Not for data you want to change without rebuilding.
These examples were run with GCC 15, GCC 16 and Clang 22 against a 5-byte
hello.txt containing Hello and an empty empty.bin. Blocks that need those
files are tagged nocompile.
constexpr unsigned char hello[] = {
#embed "hello.txt"
};
static_assert(sizeof hello == 5 && hello[0] == 'H');Initialising unsigned char (or std::byte-sized integers) from the int
literals is not narrowing: each value is a constant that fits.
constexpr char text[] = {
#embed "hello.txt" suffix(, 0)
};
static_assert(sizeof text == 6 && text[5] == '\0'); // std::puts(text) prints "Hello"constexpr unsigned char magic[] = {
#embed "hello.txt" limit(2) // 'H', 'e'
};
static_assert(sizeof magic == 2 && magic[1] == 'e');Skipping a header with the vendor offset (accepted by GCC 15/16 and
Clang 22; offset is applied first, then limit):
constexpr unsigned char middle[] = {
#if defined(__clang__)
#embed "hello.txt" clang::offset(1) limit(2)
#else
#embed "hello.txt" gnu::offset(1) limit(2)
#endif
};
static_assert(sizeof middle == 2 && middle[0] == 'e' && middle[1] == 'l');With C++29 that becomes #embed "hello.txt" offset(1) limit(2).
prefix and suffix are dropped for an empty resource; if_empty is used
only then. Together they keep an initializer valid either way:
constexpr unsigned char data[] = {
#embed "empty.bin" prefix(0xAA, ) suffix(, 0xBB) if_empty(0xFF)
};
static_assert(sizeof data == 1 && data[0] == 0xFF); // with hello.txt: 7 bytes, AA ... BBThis one compiles anywhere: it falls back when the file isn't there.
#if defined(__has_embed)
# if __has_embed("config.json") == __STDC_EMBED_FOUND__
# define HAVE_CONFIG 1
# endif
#endif
#ifdef HAVE_CONFIG
constexpr char config[] = {
#embed "config.json" suffix(, 0)
};
#else
constexpr char config[] = "{}";
#endif
static_assert(sizeof config >= 1);constexpr unsigned char nope[] = {
#embed "no-such-resource.bin"
};- The elements are
intliterals, not bytes. Intounsigned charthey always fit. Into a plainchar(signed on x86 and ARM64 macOS), a byte ≥ 0x80 is a narrowing conversion: GCC 15/16 reject it (narrowing conversion of '255' from 'int' to 'char'); Clang 22 accepts it silently when the resource has two or more bytes (a one-byte resource still gets the narrowing error). Useunsigned charorstd::uint8_tfor binary data. - No terminator unless you ask. A text file embedded into
char[]has no'\0'; addsuffix(, 0)(and for an empty file,if_empty(0)). prefix/suffixvanish on empty input. If the code after#embeddepends on a trailing comma fromsuffix(,), provideif_emptytoo.- Bracket form doesn't search
-I. GCC and Clang use--embed-dir=for#embed <…>; the quote form searches relative to the current file first. - Paths are relative to the source file, not the working directory, and
#linedoesn't change that. limit(0)still needs the file to exist. The resource is located (and must be processable) even when nothing is read.limit(n)with aconstexprvariable is silentlylimit(0). The argument is a#if-style expression, where an unknown identifier is0, so the resource becomes empty (verified with GCC and Clang). Use a macro.
- Resource inclusion (
#embed) — cppreference - [cpp.embed],
[cpp.cond] (
__has_embed) — C++ working draft - N5050 — C++26 draft (
[cpp.embed]; nooffset) - P3540R3 —
#embedoffset parameter (C++29) - P1967 —
#embed, a simple, scannable preprocessor-based resource acquisition method - GCC:
--embed-dir· Clang: C/C++ language status - The preprocessor