Linker error when building Windows wheel for free-threaded build of CPython 3.14

[tfpf]

Description

Bug

When building a 64-bit Windows wheel for an extension module for the free-threaded build of CPython 3.14 with Setuptools, the process terminates with a fatal error.

LINK : fatal error LNK1104: cannot open file 'python314.lib'
error: command 'C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.44.35207\bin\HostX86\x64\link.exe' failed with exit code 1104

Replication

• Create a basic extension module which uses Setuptools. build-backend = "setuptools.build_meta"
• Configure cibuildwheel to build a 64-bit Windows wheel for free-threaded CPython 3.14. build = ["cp314t-*"]

I have already set up a CI pipeline as above. See tfpf/pysorteddict at 51ab1e5b1589460fdd4586696182950bd4969b61 for the code.

I tested cibuildwheel 3.1.0, 3.2.0 and 3.3.0. All three versions exhibit the described behaviour.

Expected Result

A wheel should be built.

Actual Result

A wheel was not built; the process terminated with a linker error.

Other Information

@mxmlnkn originally mentioned this bug in #2531 (comment).

Build log

https://github.com/tfpf/pysorteddict/actions/runs/19801860555/job/56730312282

CI config

https://github.com/tfpf/pysorteddict/blob/51ab1e5b1589460fdd4586696182950bd4969b61/.github/workflows/ci.yml

[joerick]

Can I just check a couple things? We do test the situation you specified above in our integration test, so there must be more going on in your example

• could you try without the setuptools pin?
• could you try without the link-time optimisation flag?

[tfpf]

@joerick Removing the link-time optimisation flag does not solve the problem.

• Code: tfpf/pysorteddict at bd7433eaf9753b2d4cdb11ccab2418096ecd7c6c
• Build log: https://github.com/tfpf/pysorteddict/actions/runs/19802074896/job/56730824657
• CI configuration: https://github.com/tfpf/pysorteddict/blob/bd7433eaf9753b2d4cdb11ccab2418096ecd7c6c/.github/workflows/ci.yml

Unpinning Setuptools works!

• Code: tfpf/pysorteddict at 5c2fa1b42128a0126ba8a6fe2b42a47ca9debd3e
• Build log: https://github.com/tfpf/pysorteddict/actions/runs/19865006417/job/56925168664
  • It failed, but that's only because my test suite expected functionality which I removed to create a MWE.
• CI configuration: https://github.com/tfpf/pysorteddict/blob/5c2fa1b42128a0126ba8a6fe2b42a47ca9debd3e/.github/workflows/ci.yml

However, that is not an option for me because the PyPy builds then fail. (This has been reported in #2015.) I know that PyPy 3.11 doesn't have this issue, but I'd like to support the affected PyPy 3.10 although it is end-of-life because CPython 3.10 is still supported.

• Code: tfpf/pysorteddict at 4414b7ed8ce59f19bce7b5757f2acdc25ec823ac
• Build log: https://github.com/tfpf/pysorteddict/actions/runs/19864956148/job/56924981399
• CI configuration: https://github.com/tfpf/pysorteddict/blob/4414b7ed8ce59f19bce7b5757f2acdc25ec823ac/.github/workflows/ci.yml

Are there any easy workarounds?

[henryiii]

Could you pin setuptools only on older PyPy, then? Something like this:

[build-system]
requires = [
    "setuptools==72.1.0; platform_python_implementation == 'PyPy' and python_version < '3.11'",
    "setuptools",
]

[tfpf]

Could you pin setuptools only on older PyPy, then? Something like this:

[build-system]
requires = [
"setuptools==72.1.0; platform_python_implementation == 'PyPy' and python_version < '3.11'",
"setuptools",
]

That trick solves everything; thank you!

Do you think that perhaps a documentation update might be useful for people who encounter similar errors in the future? Perhaps a new section on the tips and trick page, like Tips and tricks - cibuildwheel | Windows: 'ImportError: DLL load failed: The specific module could not be found'. (Unless this is too niche/simple an issue to highlight.)

[mxmlnkn]

I have had the same pinning to <72 for the same PyPy reason, and the more fine-grained pinning also works for one project of mine. Thanks to all involved in pinning down this issue! I'd say that this issue and the solution should already be quite discoverable via any search.

My second project requires the additional pin of setuptools < 74 because of pypa/setuptools#4612, and neither setuptools 72 nor 73 seems to be sufficient to fix the python314.lib problem. The Python build ecosystem is cursed. Guess, I'll live without Windows cp314t support for that project for now.

[henryiii]

IMO, you should not be supporting anything other than the (assumed to be final) release of PyPy. Windows Python 3.14t is much more important than pypy<3.11. It's also the final release of PyPy, so maybe everyone will stick with that one for a while.

Old versions of setuptools will stop working eventually, either due to Python updates, OS updates, or other updates. Python 3.14t being one example. Do you know why you need distutils.msvccompiler? That's been deprecated for years and gone for a year, so that probably is a problem if you need it.

The Python build ecosystem is cursed

No, setuptools is cursed due to it's age and growth from distutils. Scikit-build-core, meson-python, and Maturin are fantastic, clean, modern, and don't have these sorts of issues. :D

[henryiii]

Here's an example I found of someone using a workaround: https://github.com/pygame/pygame/pull/4538/files

Perhaps a new section on the tips and trick page

Maybe, in a setuptools specific section? Many major projects have moved to scikit-build-core and meson-python, or hatchling plugins, and there's also Maturin for the Rust rewrites, so it's only for the subset of users stuck still doing binary builds on setuptools.

[mxmlnkn]

Thanks for the support. Sorry for veering a bit off-topic. So, basically, I'll have to fall back to an import from setuptools._distutils._msvccompiler. If it works, it works, I guess. I'll give it a try. I am using MSVCCompiler to compile ISA-L with NASM. Ideally, it would be nice if I could hack Python library building into the existing CMake build system of my project... when I find motivation to spend more time on the build system instead of code.