# Core Header Files in fmtlib: A Complete Guide to the {fmt} Library Architecture

> Explore the core header files of fmtlib, including fmt/core.h and fmt/format.h. Understand the architecture of this powerful C++ formatting library for efficient, type-safe string manipulation.

- Repository: [Hello World Foundation/fmt](https://github.com/fmtlib/fmt)
- Tags: internals
- Published: 2026-09-10

---

**The {fmt} library requires only four core header files—[`fmt/core.h`](https://github.com/fmtlib/fmt/blob/main/fmt/core.h), [`fmt/format.h`](https://github.com/fmtlib/fmt/blob/main/fmt/format.h), [`fmt/args.h`](https://github.com/fmtlib/fmt/blob/main/fmt/args.h), and [`fmt/compile.h`](https://github.com/fmtlib/fmt/blob/main/fmt/compile.h)—to provide type-safe, compile-time-checked string formatting, with additional headers available for specialized features like colors, chrono, ranges, and wide characters.**

The `fmtlib/fmt` repository organizes its public API into a modular header structure under `include/fmt/`, allowing you to include only the **core header files** your project actually needs. Understanding this architecture helps minimize compile times and linking overhead while giving you access to the library's full formatting capabilities, from basic string interpolation to compile-time format string parsing.

## The Minimal Core: Four Headers for Essential Formatting

The foundational layer of fmtlib consists of four headers that implement the complete formatting engine. These files depend on each other hierarchically and provide everything needed for type-safe formatting without pulling in standard library I/O or platform-specific code.

### fmt/core.h: The Foundation

[`include/fmt/core.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/core.h) defines the library's fundamentals: the namespace macros (`FMT_BEGIN_NAMESPACE`, `FMT_END_NAMESPACE`), the `string_view` class for lightweight string handling, and feature-detection macros like `FMT_CONSTEXPR` and `FMT_NODISCARD`. Every other header in the library includes this file, making it the non-negotiable starting point for any fmtlib usage.

### fmt/format.h: The Public API

[`include/fmt/format.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/format.h) exposes the high-level formatting functions you call in application code: `fmt::format()`, `fmt::format_to()`, `fmt::print()`, and `fmt::vformat()`. It also declares the `formatter` template that you specialize to add custom type support. When you include [`format.h`](https://github.com/fmtlib/fmt/blob/main/format.h), you gain access to the full runtime formatting engine with locale support and buffer management.

### fmt/args.h: Type-Erased Argument Storage

[`include/fmt/args.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/args.h) implements the machinery that makes variadic templates efficient. It declares `basic_format_arg`, `basic_format_args`, and `format_args`, which store type-erased references to your formatting arguments. This header allows the formatting engine to process heterogeneous argument packs without virtual function overhead, as detailed in the `dynamic_format_arg_store` implementation.

### fmt/compile.h: Compile-Time Parsing

[`include/fmt/compile.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/compile.h) enables zero-overhead format string parsing through the `FMT_COMPILE` macro and `compile_parse_context`. When you wrap format strings with `FMT_COMPILE("...")`, the library parses the string at compile time, converting it into a constexpr representation that eliminates runtime parsing overhead entirely.

```cpp
// Minimal example using only the four core headers
#include <fmt/core.h>
#include <fmt/format.h>
#include <fmt/args.h>
#include <fmt/compile.h>

int main() {
    constexpr auto compiled = FMT_COMPILE("Value: {}, Code: {}");
    std::string result = fmt::format(compiled, 42, "OK");
    fmt::print("{}\n", result);
}

```

## Extension Headers for Specialized Domains

Beyond the minimal core, fmtlib provides opt-in headers that extend functionality into specific domains without bloating the base installation.

### I/O Stream and Legacy Support

- **[`fmt/ostream.h`](https://github.com/fmtlib/fmt/blob/main/fmt/ostream.h)** – Bridges fmtlib with `std::ostream` by providing `ostream_formatter` and `operator<<` overloads, allowing you to format types that already stream to standard output.
- **[`fmt/printf.h`](https://github.com/fmtlib/fmt/blob/main/fmt/printf.h)** – Offers `fmt::printf()` and `fmt::sprintf()` functions that use printf-style format strings while maintaining type safety through the core formatting engine.

### Visual and Temporal Formatting

- **[`fmt/color.h`](https://github.com/fmtlib/fmt/blob/main/fmt/color.h)** – Adds terminal color support through `fmt::color` enumerations and the `fmt::styled()` function, enabling syntax like `fmt::print(fg(fmt::color::red), "Error\n")`.
- **[`fmt/chrono.h`](https://github.com/fmtlib/fmt/blob/main/fmt/chrono.h)** – Supplies formatters for `std::chrono` types, allowing direct formatting of time points and durations using strftime-style specifiers like `{:%Y-%m-%d %H:%M:%S}`.

### Container and Standard Library Extensions

- **[`fmt/ranges.h`](https://github.com/fmtlib/fmt/blob/main/fmt/ranges.h)** – Implements `range_formatter` to handle containers, arrays, and tuples, automatically formatting elements delimited by brackets and commas.
- **[`fmt/std.h`](https://github.com/fmtlib/fmt/blob/main/fmt/std.h)** – Contains specializations for modern standard library types including `std::optional`, `std::variant`, and `std::path` that are not covered by the core headers.
- **[`fmt/enum.h`](https://github.com/fmtlib/fmt/blob/main/fmt/enum.h)** – Provides generic enum formatting utilities and `operator<<` implementations for enumeration types.

### Platform and Character Support

- **[`fmt/os.h`](https://github.com/fmtlib/fmt/blob/main/fmt/os.h)** – Contains OS-specific utilities including `fmt::system_error` for error-code formatting and platform detection macros like `FMT_WIN32`.
- **[`fmt/xchar.h`](https://github.com/fmtlib/fmt/blob/main/fmt/xchar.h)** – Adds support for wide and UTF character types (`wchar_t`, `char16_t`, `char32_t`, `char8_t`) through specializations of `basic_format_context`.

### C Interface

- **[`fmt/fmt-c.h`](https://github.com/fmtlib/fmt/blob/main/fmt/fmt-c.h)** – Declares the C API (`fmt_c_print`, `fmt_c_format`) that wraps the C++ core for use in C translation units or FFI scenarios.

## Implementation Internals

### fmt/format-inl.h: Header-Only Optimizations

[`include/fmt/format-inl.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/format-inl.h) contains inline implementations of performance-critical functions, particularly floating-point formatting and buffer operations. This header is automatically included by [`format.h`](https://github.com/fmtlib/fmt/blob/main/format.h) when you define `FMT_HEADER_ONLY`, ensuring that inline functions are available in header-only mode without violating the One Definition Rule.

```cpp
// Example: Using chrono and color extensions
#include <fmt/core.h>
#include <fmt/chrono.h>
#include <fmt/color.h>
#include <chrono>

int main() {
    auto now = std::chrono::system_clock::now();
    fmt::print(fg(fmt::color::green), 
               "Build time: {:%Y-%m-%d %H:%M:%S}\n", 
               now);
}

```

## Summary

- **Four headers form the minimal core**: [`core.h`](https://github.com/fmtlib/fmt/blob/main/core.h), [`format.h`](https://github.com/fmtlib/fmt/blob/main/format.h), [`args.h`](https://github.com/fmtlib/fmt/blob/main/args.h), and [`compile.h`](https://github.com/fmtlib/fmt/blob/main/compile.h) provide complete type-safe formatting with compile-time checks.
- **Specialized features require specific includes**: Colors, chrono, ranges, and wide characters each have dedicated headers to control compilation overhead.
- **Modularity preserves performance**: The separation between [`format.h`](https://github.com/fmtlib/fmt/blob/main/format.h) (interface) and [`format-inl.h`](https://github.com/fmtlib/fmt/blob/main/format-inl.h) (implementation) supports both shared-library and header-only consumption models.
- **C and legacy APIs remain available**: Headers like [`fmt/printf.h`](https://github.com/fmtlib/fmt/blob/main/fmt/printf.h) and [`fmt/fmt-c.h`](https://github.com/fmtlib/fmt/blob/main/fmt/fmt-c.h) provide migration paths from older formatting systems.

## Frequently Asked Questions

### What is the smallest set of fmtlib headers needed for basic string formatting?

You need only **[`fmt/core.h`](https://github.com/fmtlib/fmt/blob/main/fmt/core.h)** and **[`fmt/format.h`](https://github.com/fmtlib/fmt/blob/main/fmt/format.h)** for basic usage. [`core.h`](https://github.com/fmtlib/fmt/blob/main/core.h) provides the fundamental types and macros, while [`format.h`](https://github.com/fmtlib/fmt/blob/main/format.h) supplies `fmt::format()` and `fmt::print()`. If you require compile-time format string parsing, also include [`fmt/compile.h`](https://github.com/fmtlib/fmt/blob/main/fmt/compile.h).

### Does including [`fmt/format.h`](https://github.com/fmtlib/fmt/blob/main/fmt/format.h) automatically include all extension headers?

No. [`fmt/format.h`](https://github.com/fmtlib/fmt/blob/main/fmt/format.h) includes [`fmt/core.h`](https://github.com/fmtlib/fmt/blob/main/fmt/core.h) and [`fmt/args.h`](https://github.com/fmtlib/fmt/blob/main/fmt/args.h) internally, but extension headers like [`fmt/color.h`](https://github.com/fmtlib/fmt/blob/main/fmt/color.h), [`fmt/chrono.h`](https://github.com/fmtlib/fmt/blob/main/fmt/chrono.h), and [`fmt/ranges.h`](https://github.com/fmtlib/fmt/blob/main/fmt/ranges.h) remain separate. You must include them explicitly when using those features to avoid unnecessary compilation overhead.

### How does [`fmt/format-inl.h`](https://github.com/fmtlib/fmt/blob/main/fmt/format-inl.h) differ from other headers in the library?

[`fmt/format-inl.h`](https://github.com/fmtlib/fmt/blob/main/fmt/format-inl.h) contains implementation details rather than public API declarations. It is included automatically when using header-only mode (`FMT_HEADER_ONLY`) to provide inline definitions for performance-critical functions. In compiled library mode, these implementations reside in the compiled binary instead.