pybind11 warning in O3 optimization with gcc

[Sytoplis]

Hello. Similar to #3014 I have the issue that i get a lot of warnings when compiling using gcc. I am not yet beyond the example with using this library, so i am kind of new here. I am compiling my file using
gcc -O3 -Wall -shared -std=c++11 -fPIC $(python3-config --includes) -I "$PYBIND11_BASE/include" example.cpp -o "example$(python3-config --extension-suffix)"
This is how it is suggested in the docs, so i am unsure what i am doing wrong. (It was suggested here https://pybind11.readthedocs.io/en/stable/compiling.html#building-manually)

Getting warnings like:

/usr/include/c++/16/bits/stl_bvector.h:303:21: warning: ‘((const std::_Bit_iterator*)((char*)&used_kwargs + offsetof(pybind11::detail::small_vector<bool, 6>,pybind11::detail::small_vector<bool, 6>::m_repr) + 8))[1].std::_Bit_iterator::std::_Bit_iterator_base.std::_Bit_iterator_base::_M_offset’ may be used uninitialized [-Wmaybe-uninitialized]
  303 |               + __x._M_offset - __y._M_offset);
      |                 ~~~~^~~~~~~~~

All of the warnings are -Wmaybe-uninitialized by the way. And they all come from stl_bvector.h

Other than that, it compiles just fine. Not sure if this is my fault or a bug.
I am on Linux (fedora 44) using the pybind11 release 3.0.4

[kouya-marino]

Short answer: not your fault, and not a bug in your code. It's a GCC false positive, and the code it's complaining about is pybind11's own — new code that landed in 3.0.2. Your module is fine. It's also, as far as I can tell, unreported, so it's worth a proper bug report.

What the warning is actually pointing at

#3014 is a different problem (that one is Eigen's DenseStorage.h inlined into the Eigen type caster; its workaround landed in #5516 and is already in your 3.0.4). Same diagnostic name, same "GCC + optimizer + a pybind11 header" shape, different code.

Yours decodes cleanly onto pybind11 3.0.x internals:

• used_kwargs is declared in the call dispatcher: include/pybind11/pybind11.h:1100, as small_vector<bool, arg_vector_small_size>, and arg_vector_small_size = 6 (cast.h:2090) — hence small_vector<bool, 6> in the message.
• small_vector<bool, N> (detail/argument_vector.h:222) has exactly one member, m_repr, which is a hand-rolled tagged union: either an inline bitset, or a heap std::vector<bool>.
• So (char*)&used_kwargs + offsetof(..., m_repr) + 8 is the std::vector<bool> sitting in the union's heap arm; [1] is the second _Bit_iterator in libstdc++'s _Bvector_impl_data, i.e. _M_finish; _M_offset is its bit offset. Read as English, GCC is saying: "used_kwargs.m_repr.hvector.vec._M_finish._M_offset may be used uninitialized."
• stl_bvector.h:303 is operator- for bit iterators, which is where std::vector<bool>::size() ends up (size() is literally end() - begin()).

The chain is used_kwargs.size() → small_vector<bool>::size() → the heap branch → vec.size() → bit-iterator subtraction.

Why it's a false positive: the union's tag is read by memcpy-ing the first byte out (lines 111-124 — deliberate, to avoid reading an inactive union member). At -O3 GCC inlines everything, then its uninit pass has to prove "the constructor took the inline branch ⟹ that tag byte is 1 ⟹ the heap branch of size() is dead." Through a union, an opaque one-byte type-punned load, and a couple of PYBIND11_NOINLINE helpers, it can't, so it keeps the heap branch live and reports the storage there as never written — which, on the inline path, it genuinely never is. At runtime that branch is unreachable: it requires the tag to be 0, which only happens when the constructor took the heap path, which fully constructs the vector. (For small_vector<bool, 6> the inline capacity is actually 64 bits, so the heap arm needs more than 64 keyword arguments in one call.)

This is also why it only shows up with optimization — GCC's docs are explicit that -Wmaybe-uninitialized warnings "are only possible in optimizing compilation" and are optional "because GCC may not be able to determine when the code is correct in spite of appearing to have an error" (Warning-Options).

Honest caveat: I read the source rather than running GCC 16, so "false positive" is a confident conclusion from the code, not from an observed clean run. If you want actual certainty about your own build, valgrind --tool=memcheck on a script that exercises the module is the tool that catches real uninitialized reads (ASan/UBSan do not).

What to do about it

1. The one that definitely works — turn the diagnostic off for this build:

gcc -O3 -Wall -Wno-maybe-uninitialized -shared -std=c++11 -fPIC \
    $(python3-config --includes) -I "$PYBIND11_BASE/include" \
    example.cpp -o "example$(python3-config --extension-suffix)"

Every warning you pasted is -Wmaybe-uninitialized (it's pulled in by -Wall), so this clears the lot. You lose less than it sounds: -Wuninitialized — the "definitely uninitialized on some path" analysis, the higher-signal half — is a separate option and stays on. If you later use -Werror, prefer -Wno-error=maybe-uninitialized so the noise stays visible but non-fatal.

2. Narrower, worth trying — a pragma around the include, so your own code keeps the warning:

#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
#include <pybind11/pybind11.h>
#pragma GCC diagnostic pop

GCC checks #pragma GCC diagnostic regions against every location in the diagnostic's inlining stack, not just the caret, and several frames here are inside pybind11.h. It has to be the first inclusion of pybind11.h in the TU (include guards), and it has to be repeated per TU. Caveat: suppressing late middle-end warnings this way is not 100% reliable — in #5516 the original reporter found a similar pragma didn't fully silence his build — so if it doesn't take, fall back to option 1.

Things that look like fixes but aren't:

• Upgrading. detail/argument_vector.h is byte-identical in 3.0.2, 3.0.3, 3.0.4, 3.1.0 and current master, and there's no suppression anywhere near used_kwargs. 3.1.0 will not help.
• -isystem instead of -I for the pybind11 headers. The obvious guess, but almost certainly not effective here: GCC only suppresses a middle-end warning when every frame of the inlining stack is a system header, and the outermost frame is your example.cpp. That behaviour is intended, not a GCC defect: PR 109559 ("Unexpected -Wmaybe-uninitialized warning when inlining with system header") was closed INVALID. The clincher is your own log: the caret is already inside /usr/include/c++/16/..., a system header by any measure, and it warned anyway. I haven't run it on GCC 16, and it's a 30-second experiment if you're curious — -isystem is a good habit regardless — but I wouldn't expect it to work.
• Dropping to -O2. Might move or hide it, might not; [QUESTION] pybind11+eigen warning in O2 optimization with gcc #3014 was reported at -O2. Not worth trading codegen for.

Downgrading to 3.0.1 would make it go away (argument_vector.h doesn't exist before 3.0.2), but that's only useful as a bisect data point, not as a recommendation.

Unrelated, but check it: gcc vs c++

The docs command is c++ -O3 -Wall -shared ...; you're using gcc. That doesn't change the warnings at all — gcc picks the C++ front end from the .cpp extension, so the compile is correct. But per Invoking G++, "the use of gcc does not add the C++ library," and with -shared unresolved symbols aren't a link error, so you can end up with a .so that has dangling libstdc++ symbols (operator new, __cxa_throw, the __cxxabiv1 vtables…). That typically shows up as an ImportError: undefined symbol: ... — or, more annoyingly, works by accident whenever something already loaded libstdc++ into the process (numpy and most C++ extensions do). Quick check:

ldd -r ./example*.so 2>&1 | grep undefined
nm -D --undefined-only ./example*.so | c++filt | grep -E 'std::|__cxa'

If that lights up, just use c++ (or g++) as the docs say. I'm inferring the import failure from the documented driver behavior rather than having reproduced it on Fedora, so treat it as "worth checking," not "definitely broken."

Please file this as an issue

I couldn't find this reported anywhere — no pybind11 issue, PR or discussion mentions stl_bvector or this small_vector<bool> site, and nothing in GCC's Bugzilla covers a vector<bool> / _Bit_iterator::_M_offset false positive either. The code came in with #5824 (inline storage for small argument lists) and #5948 (vectorcall), and pybind11's CI tops out at GCC 13 and builds tests as MinSizeRel, so GCC 15/16 at -O3 is simply untested territory — that's why nobody's hit it upstream.

If you open a [BUG] issue, include: the exact g++ --version, the exact compile command, the full unabridged warning log (with the note: ... inlined from ... lines, which are the useful part), and ideally a self-contained example.cpp. A bare warning dump tends to stall: #6030, the other open report in this class, has sat since April with a single comment. The likely fix is a PYBIND11_WARNING_PUSH / PYBIND11_WARNING_DISABLE_GCC("-Wmaybe-uninitialized") / PYBIND11_WARNING_POP around the heap branch in small_vector<bool>, which is the same shape as the merged #5908 (a -Warray-bounds false positive in this same container) — but a reproducer first, since a narrower code change might avoid the warning outright and would be the better fix.

[Sytoplis]

Thank you so much for your elaborate answer. I already had the idea of putting pragmas around the include to suppress the warning, but this is not ideal and should be probably rather fixed in pybind11. I gathered some more information and filed a proper bug report, which mentions also this discussion (#6167). I also tried a few of your fixes, like using -isystem instead if -I or trying c++ and g++ instead of gcc, but the warnings stay. I did not do ldd and nm command line thing, as i do not have ldd installed.
I will close this discussion, because an issue on this topic exists now.