Skip to content

fix(cmake): allow opting out of system pybind11 headers - #6171

Open
JOINKINGER wants to merge 2 commits into
pybind:masterfrom
JOINKINGER:fix/5937-subdirectory-header-precedence
Open

fix(cmake): allow opting out of system pybind11 headers#6171
JOINKINGER wants to merge 2 commits into
pybind:masterfrom
JOINKINGER:fix/5937-subdirectory-header-precedence

Conversation

@JOINKINGER

@JOINKINGER JOINKINGER commented Sep 3, 2026

Copy link
Copy Markdown

Description

When pybind11 is added as a subdirectory, its headers are marked as SYSTEM.
A parent project that globally adds an include prefix containing another
pybind11 installation can therefore select that installed copy before the
subdirectory source tree.

Add PYBIND11_USE_SYSTEM_HEADERS, enabled by default to preserve the existing
behavior. Setting it to OFF before add_subdirectory(pybind11) makes
pybind11_add_module() prefer the subdirectory headers.

Add a CMake regression test with a conflicting fake installed header. The test
covers both FindPython and classic CMake paths.

Fixes #5937

Suggested changelog entry:

  • Added a PYBIND11_USE_SYSTEM_HEADERS option for add_subdirectory users
    that need pybind11 source headers to take precedence over parent include
    directories.

📚 Documentation preview 📚: https://pybind11--6171.org.readthedocs.build/

@JOINKINGER
JOINKINGER requested a review from henryiii as a code owner September 3, 2026 21:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG]: CMake add_subdirectory() interference from system-installed pybind11

1 participant