Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
September 26, 2023 14:10
September 26, 2023 14:04
January 8, 2023 07:53
December 29, 2019 11:30
December 31, 2020 10:37
June 20, 2019 20:32
December 4, 2023 11:43


Build status Try it online License: MIT

A macro for printf-style debugging fans.

Debuggers are great. But sometimes you just don't have the time or patience to set up everything correctly and just want a quick way to inspect some values at runtime.

This projects provides a single header file with a dbg(…) macro that can be used in all circumstances where you would typically write printf("…", …) or std::cout << …. But it comes with a few extras.


#include <dbg.h>
#include <cstdint>
#include <vector>

// You can use "dbg(..)" in expressions:
int32_t factorial(int32_t n) {
  if (dbg(n <= 1)) {
    return dbg(1);
  } else {
    return dbg(n * factorial(n - 1));

int32_t main() {
  std::string message = "hello";
  dbg(message);  // [example.cpp:15 (main)] message = "hello" (std::string)

  const int32_t a = 2;
  const int32_t b = dbg(3 * a) + 1;  // [example.cpp:18 (main)] 3 * a = 6 (int32_t)

  std::vector<int32_t> numbers{b, 13, 42};
  dbg(numbers);  // [example.cpp:21 (main)] numbers = {7, 13, 42} (std::vector<int32_t>)

  dbg("this line is executed");  // [example.cpp:23 (main)] this line is executed


  return 0;

The code above produces this output (try it yourself):

dbg(…) macro output


  • Easy to read, colorized output (colors auto-disable when the output is not an interactive terminal)
  • Prints file name, line number, function name and the original expression
  • Adds type information for the printed-out value
  • Specialized pretty-printers for containers, pointers, string literals, enums, std::optional, etc.
  • Can be used inside expressions (passing through the original value)
  • The dbg.h header issues a compiler warning when included (so you don't forget to remove it).
  • Compatible and tested with C++11, C++14 and C++17.


To make this practical, the dbg.h header should be readily available from all kinds of different places and in all kinds of environments. The quick & dirty way is to actually copy the header file to /usr/local/include or to clone the repository and symlink dbg.h to /usr/local/include/dbg.h.

git clone
sudo ln -s $(readlink -f dbg-macro/dbg.h) /usr/local/include/dbg.h

If you don't want to make untracked changes to your filesystem, check below if there is a package for your operating system or package manager.

On Arch Linux

You can install dbg-macro from the AUR:

yay -S dbg-macro

With vcpkg

You can install the dbg-macro port via:

vcpkg install dbg-macro

With cmake


cmake_minimum_required(VERSION 3.11) # FetchContent added in cmake 3.11
project(app) # name of executable


# dbg-macro

FetchContent_Declare(dbg_macro GIT_REPOSITORY

add_executable(${PROJECT_NAME} main.cpp) # your source files goes here
target_link_libraries(${PROJECT_NAME} PRIVATE dbg_macro) # make dbg.h available


#include <dbg.h>

int main() {
  dbg(42, "hello world", false);
  return 0;


  • Set the DBG_MACRO_DISABLE flag to disable the dbg(…) macro (i.e. to make it a no-op).
  • Set the DBG_MACRO_NO_WARNING flag to disable the "'dbg.h' header is included in your code base" warnings.
  • Set the DBG_MACRO_FORCE_COLOR flag to force colored output and skip tty checks.

Advanced features

Multiple arguments

You can pass multiple arguments to the dbg(…) macro. The output of dbg(x, y, z) is same as dbg(x); dbg(y); dbg(z);:

dbg(42, "hello world", false);

Note that you have to wrap "unprotected commas" in parentheses:

dbg("a vector:", (std::vector<int>{2, 3, 4}));

Hexadecimal, octal and binary format

If you want to format integers in hexadecimal, octal or binary representation, you can simply wrap them in dbg::hex(…), dbg::oct(…) or dbg::bin(…):

const uint32_t secret = 12648430;

Printing type names

dbg(…) already prints the type for each value in parenthesis (see screenshot above). But sometimes you just want to print a type (maybe because you don't have a value for that type). In this case, you can use the dbg::type<T>() helper to pretty-print a given type T. For example:

template <typename T>
void my_function_template() {
  using MyDependentType = typename std::remove_reference<T>::type&&;

Print the current time

To print a timestamp, you can use the dbg::time() helper:



If you want dbg(…) to work for your custom datatype, you can simply overload operator<< for std::ostream&:

std::ostream& operator<<(std::ostream& out, const user_defined_type& v) {
  out << "";
  return out;

If you want to modify the type name that is printed by dbg(…), you can add a custom get_type_name overload:

// Customization point for type information
namespace dbg {
    std::string get_type_name(type_tag<bool>) {
        return "truth value";


If you want to contribute to dbg-macro, here is how you can build the tests and demos:

Make sure that the submodule(s) are up to date:

git submodule update --init

Then, use the typical cmake workflow. Usage of -DCMAKE_CXX_STANDARD=17 is optional, but recommended in order to have the largest set of features enabled:

mkdir build
cd build

To run the tests, simply call:

make test

You can find the unit tests in tests/basic.cpp.


This project is inspired by Rusts dbg!(…) macro.