Incorrect Python Library Linking in Debug Builds on Windows (MSVC): Should Use python{vernum}_d.lib

[zicowarn]

Describe the bug
When building the numpy project that depends on Python using Meson on Windows with MSVC in debug mode, the final linking step incorrectly uses the release Python library (e.g. python313.lib) instead of the debug library (python313_d.lib). Even though the build logs indicate that python313_d.lib is used during compilation (as evidenced by the modifications in pyconfig.h with #pragma message directives), the resulting .pyd files are linked against the release DLL. This causes runtime issues when using a debug Python interpreter.

To Reproduce

1. Use a minimal Meson project that depends on Python. For example, create a simple meson.build that finds Python using Meson’s built-in dependency module.
2. Modify your Python installation's pyconfig.h to include:

   #if defined(_DEBUG)
       #pragma message("Use debug library, python313_d.lib")
       #pragma comment(lib,"python313_d.lib")
   #elif defined(Py_LIMITED_API)
       #pragma message("Use release library (Limited API), python3t.lib")
       #pragma comment(lib,"python3.lib")
   #else
       #pragma message("Use release library, python313.lib")
       #pragma comment(lib,"python313.lib")
   #endif

3. Create and activate a debug virtual environment using the debug interpreter (e.g. python_d.exe).
4. Run the following command to build using Spin (which uses Meson under the hood):

   python_d -m spin build -v --clean -- -Dbuildtype=debug -Ddisable-optimization=true

5. Check the final linked .pyd file (for example using Dependency Walker). You will see that it depends on python313.dll instead of python313_d.dll.

Expected behavior
In a debug build, the final linking should correctly use the debug Python library (i.e. python313_d.lib) so that the resulting .pyd depends on python313_d.dll. Our expectation is that Meson’s Python dependency module should detect the debug interpreter and adjust the link arguments accordingly. For instance, the code in mesonbuild/dependencies/python.py should choose python{vernum}_d.lib when LIBRARY ends with _d.dll.

System parameters

• Build type: Native build (no cross-compilation)
• Operating System: Windows 10
• Python Version: Python 3.13 (debug interpreter, e.g. python313_d.exe)
• Meson Version: 1.7.0
• Ninja Version: 1.11.1.git.kitware.jobserver-1

---

I propose modifying the get_windows_link_args function in mesonbuild/dependencies/python.py by adjusting the conditional block for debug builds as follows:

if is_debug_build and vscrt_debug:
    library = self.variables.get('LIBRARY', '')
    if library.endswith('_d.dll'):
        libpath = Path('libs') / f'python{vernum}_d.lib'
        mlog.warning("Using python static library with debug Python interpreter. " + libpath.name)
    if not self.variables.get('Py_DEBUG'):
        mlog.warning(textwrap.dedent('''\
            Using a debug build type with MSVC or an MSVC-compatible compiler
            when the Python interpreter is not also a debug build will almost
            certainly result in a failed build. Prefer using a release build
            type or a debug Python interpreter.
            '''))

Could this be considered for a fix? I'd be happy to submit a pull request with this change if the approach is acceptable.

---

Feel free to adjust any details as needed before submission.

[dcbaker]

@eli-schwartz, @rgommers, just to ping a few people that are probably relevant

[rgommers]

That patch seems correct at first sight. I'd have to refresh my memory on #10776 (comment) and test to be sure, this logic is annoyingly complex - happy to do so if you put up a PR.

Adding a link to the relevant code block to help other readers:

meson/mesonbuild/dependencies/python.py

Lines 241 to 263 in 19482e4

	# For a debug build, pyconfig.h may force linking with
	# pythonX_d.lib (see meson#10776). This cannot be avoided
	# and won't work unless we also have a debug build of
	# Python itself (except with pybind11, which has an ugly
	# hack to work around this) - so emit a warning to explain
	# the cause of the expected link error.
	buildtype = self.env.coredata.optstore.get_value_for(OptionKey('buildtype'))
	assert isinstance(buildtype, str)
	debug = self.env.coredata.optstore.get_value_for(OptionKey('debug'))
	# `debugoptimized` buildtype may not set debug=True currently, see gh-11645
	is_debug_build = debug or buildtype == 'debug'
	vscrt_debug = False
	if OptionKey('b_vscrt') in self.env.coredata.optstore:
	vscrt = self.env.coredata.optstore.get_value('b_vscrt')
	if vscrt in {'mdd', 'mtd', 'from_buildtype', 'static_from_buildtype'}:
	vscrt_debug = True
	if is_debug_build and vscrt_debug and not self.variables.get('Py_DEBUG'):
	mlog.warning(textwrap.dedent('''\
	Using a debug build type with MSVC or an MSVC-compatible compiler
	when the Python interpreter is not also a debug build will almost
	certainly result in a failed build. Prefer using a release build
	type or a debug Python interpreter.
	'''))

[zicowarn]

@rgommers

I have read comment #10776 you mentioned. I also agree that adopting a pybind11-like approach is inappropriate, and the added warning in the discussion is highly beneficial.

Regarding the issue described here, prior to using Meson for compilation, I assumed that simply using the "correct" interpreter would allow Meson to locate the corresponding Python library files. However, during compilation, I consistently encountered linkage errors to incorrect Python libraries. This problem was only identified after analyzing the python.py file, which prompted me to submit this issue.

I believe that Meson, as a build tool, should only require configuring the appropriate library settings in the build environment when compiling Python-related projects that include Python.h. While my understanding of Meson may not be comprehensive, if I'm correct, Meson currently retrieves sysconfig information from the interpreter in the current Python environment (including virtual environments), which is exactly what python_info.py does. This implementation raises two concerns:

Static library lookup should prioritize using the LIBRARY or LDLIBRARY entries in the variables dictionary to obtain the static library filename, rather than relying solely on py_version_nodot. This is because py_version_nodot values remain identical across all Python executable variants.

Py_DEBUG, The Py_DEBUG flag is not a standard sysconfig variable. Its presence depends on explicit settings in build scripts. Therefore, Python installations from official packages may not have Py_DEBUG defined in sysconfig.

The LIBRARY and LDLIBRARY members mentioned above should always exist, as evidenced by the following code snippet from sysconfig/__init__.py:

def _init_non_posix(vars):
    """Initialize the module as appropriate for NT"""
    # set basic install directories
    import _winapi
    import _sysconfig
    vars['BINLIBDEST'] = get_path('platstdlib')
    vars['LIBDEST'] = get_path('stdlib')
    vars['INCLUDEPY'] = get_path('include')

    # Add EXT_SUFFIX, SOABI, and Py_GIL_DISABLED
    vars.update(_sysconfig.config_vars())

    vars['LIBDIR'] = _safe_realpath(os.path.join(get_config_var('installed_base'), 'libs'))
    if hasattr(sys, 'dllhandle'):
        dllhandle = _winapi.GetModuleFileName(sys.dllhandle)
        vars['LIBRARY'] = os.path.basename(_safe_realpath(dllhandle))
        vars['LDLIBRARY'] = vars['LIBRARY']
    vars['EXE'] = '.exe'
    vars['VERSION'] = _PY_VERSION_SHORT_NO_DOT
    vars['BINDIR'] = os.path.dirname(_safe_realpath(sys.executable))
    vars['TZPATH'] = ''

In the above context, for the problem described in this issue, I personally feel that for the windows (MSVC) compilation environment, there can be two modifications (files mesonbuild/dependencies/python.py) possible for the problem:

• Aggressive approach

if comp.id == "gcc":
    if imp_lower == 'pypy' and verdot == '3.8':
        # The naming changed between 3.8 and 3.9
        libpath = Path('libpypy3-c.dll')
    elif imp_lower == 'pypy':
        libpath = Path(f'libpypy{verdot}-c.dll')
    else:
        libpath = Path(f'python{vernum}.dll')
else:
    library = self.variables.get('LIBRARY', '')
    if library.endswith('.dll'):
        libpath =  Path('libs') / library.replace('.dll', '.lib')
    else:
        if self.is_freethreaded:
            libpath = Path('libs') / f'python{vernum}t.lib'
        else:
            libpath = Path('libs') / f'python{vernum}.lib'
    mlog.log("Using python static library: " + libpath.name)
    # For a debug build, pyconfig.h may force linking with
    # pythonX_d.lib (see meson#10776). This cannot be avoided
    # and won't work unless we also have a debug build of
    # Python itself (except with pybind11, which has an ugly
    # hack to work around this) - so emit a warning to explain
    # the cause of the expected link error.
    buildtype = self.env.coredata.get_option(mesonlib.OptionKey('buildtype'))
    debug = self.env.coredata.get_option(mesonlib.OptionKey('debug'))
    # `debugoptimized` buildtype may not set debug=True currently, see gh-11645
    is_debug_build = debug or buildtype == 'debug'
    vscrt_debug = False
    if mesonlib.OptionKey('b_vscrt') in self.env.coredata.optstore:
        vscrt = self.env.coredata.optstore.get_value('b_vscrt')
        if vscrt in {'mdd', 'mtd', 'from_buildtype', 'static_from_buildtype'}:
            vscrt_debug = True
    if is_debug_build and vscrt_debug and not self.variables.get('Py_DEBUG'):
        mlog.warning(textwrap.dedent('''\
            Using a debug build type with MSVC or an MSVC-compatible compiler
            when the Python interpreter is not also a debug build will almost
            certainly result in a failed build. Prefer using a release build
            type or a debug Python interpreter.
            '''))

• Conservative approach

if comp.id == "gcc":
    if imp_lower == 'pypy' and verdot == '3.8':
        # The naming changed between 3.8 and 3.9
        libpath = Path('libpypy3-c.dll')
    elif imp_lower == 'pypy':
        libpath = Path(f'libpypy{verdot}-c.dll')
    else:
        libpath = Path(f'python{vernum}.dll')
else:
    if self.is_freethreaded:
        libpath = Path('libs') / f'python{vernum}t.lib'
    else:
        libpath = Path('libs') / f'python{vernum}.lib'
    # For a debug build, pyconfig.h may force linking with
    # pythonX_d.lib (see meson#10776). This cannot be avoided
    # and won't work unless we also have a debug build of
    # Python itself (except with pybind11, which has an ugly
    # hack to work around this) - so emit a warning to explain
    # the cause of the expected link error.
    buildtype = self.env.coredata.get_option(mesonlib.OptionKey('buildtype'))
    debug = self.env.coredata.get_option(mesonlib.OptionKey('debug'))
    # `debugoptimized` buildtype may not set debug=True currently, see gh-11645
    is_debug_build = debug or buildtype == 'debug'
    vscrt_debug = False
    if mesonlib.OptionKey('b_vscrt') in self.env.coredata.optstore:
        vscrt = self.env.coredata.optstore.get_value('b_vscrt')
        if vscrt in {'mdd', 'mtd', 'from_buildtype', 'static_from_buildtype'}:
            vscrt_debug = True
    if is_debug_build and vscrt_debug:
        library = self.variables.get('LIBRARY', '')
        if library.endswith('_d.dll'):
            if self.is_freethreaded:
                libpath = Path('libs') / f'python{vernum}t_d.lib'
            else:
                libpath = Path('libs') / f'python{vernum}_d.lib'
            mlog.warning("Using python static library with debug Python interpreter. " + libpath.name)
        if not self.variables.get('Py_DEBUG'):
            mlog.warning(textwrap.dedent('''\
                Using a debug build type with MSVC or an MSVC-compatible compiler
                when the Python interpreter is not also a debug build will almost
                certainly result in a failed build. Prefer using a release build
                type or a debug Python interpreter.
                '''))

I fully acknowledge that my Meson expertise is limited compared to yours, and these suggestions may not be comprehensive. I welcome any corrections or feedback on these proposals.

[eli-schwartz]

Py_DEBUG, The Py_DEBUG flag is not a standard sysconfig variable. Its presence depends on explicit settings in build scripts. Therefore, Python installations from official packages may not have Py_DEBUG defined in sysconfig.

https://peps.python.org/pep-0739/ may be relevant here. :)