♻️ Replace pybind11 with nanobind

.github/workflows/ci.yml

@@ -146,7 +146,6 @@ jobs:
       contents: read
       id-token: write
 
-  # to properly link python bindings, the target must be enabled and pybind11 must be installed
   cpp-linter:
     name: 🇨‌ Lint
     needs: change-detection
@@ -156,7 +155,7 @@ jobs:
       clang-version: 20
       cmake-args: -DBUILD_MQT_QMAP_BINDINGS=ON
       files-changed-only: true
-      install-pkgs: "pybind11==3.0.1"
+      install-pkgs: "nanobind==2.10.2"
       setup-python: true
       setup-z3: true
       cpp-linter-extra-args: "-std=c++20"

.pre-commit-config.yaml

@@ -134,7 +134,7 @@ repos:
       - id: disallow-caps
         name: Disallow improper capitalization
         language: pygrep
-        entry: PyBind|Numpy|Cmake|CCache|Github|PyTest|Mqt|Tum
+        entry: Nanobind|Numpy|Cmake|CCache|Github|PyTest|Mqt|Tum
         exclude: .pre-commit-config.yaml
 
   # Check best practices for scientific Python code

CHANGELOG.md

@@ -11,7 +11,12 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#unreleased)._
 
-## [3.5.0]
+### Changed
+
+- ♻️ Migrate Python bindings from `pybind11` to `nanobind` ([#911]) ([**@denialhaag**])
+- 📦️ Provide Stable ABI wheels for Python 3.12+ ([#911]) ([**@denialhaag**])
+
+## [3.5.0] - 2025-12-16
 
 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#350)._
 
@@ -178,6 +183,7 @@ _📚 Refer to the [GitHub Release Notes] for previous changelogs._
 
 <!-- PR links -->
 
+[#911]: https://github.com/munich-quantum-toolkit/qmap/pull/911
 [#874]: https://github.com/munich-quantum-toolkit/qmap/pull/874
 [#862]: https://github.com/munich-quantum-toolkit/qmap/pull/862
 [#859]: https://github.com/munich-quantum-toolkit/qmap/pull/859

CMakeLists.txt

@@ -59,10 +59,8 @@ if(BUILD_MQT_QMAP_BINDINGS)
   endif()
 
   # top-level call to find Python
-  find_package(
-    Python 3.10 REQUIRED
-    COMPONENTS Interpreter Development.Module
-    OPTIONAL_COMPONENTS Development.SABIModule)
+  find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module
+                                               ${SKBUILD_SABI_COMPONENT})
 endif()
 
 # check if this is the master project or used via add_subdirectory

UPGRADING.md

@@ -4,6 +4,18 @@ This document describes breaking changes and how to upgrade. For a complete list
 
 ## [Unreleased]
 
+### Stable ABI wheels
+
+We are now providing Stable ABI wheels instead of separate version-specific wheels for Python 3.12+.
+This was enabled by migrating our Python bindings from `pybind11` to `nanobind`.
+
+The full list of wheels now reads:
+
+- 3.10
+- 3.11
+- 3.12+ Stable ABI
+- 3.14t
+
 ## [3.5.0]
 
 As part of this release, the scheduler of the zoned neutral atom compiler now features a new parameter `max_filling_factor`.
@@ -26,7 +38,7 @@ The hybrid mapper now also optionally yields a `.naviz` output which can be hand
 
 Free-threading Python was introduced as an experimental feature in Python 3.13.
 It became stable in Python 3.14.
-To conserve space on PyPI and to reduce the CD build times, we have removed all wheels for Python 3.13t from our CI.
+To conserve space on PyPI and to reduce the CI/CD build times, we have removed all wheels for Python 3.13t.
 We continue to provide wheels for the regular Python versions 3.10 to 3.14, as well as 3.14t.
 
 ## [3.4.0]

bindings/clifford_synthesis/CMakeLists.txt

@@ -6,7 +6,7 @@
 #
 # Licensed under the MIT License
 
-add_mqt_python_binding(
+add_mqt_python_binding_nanobind(
   QMAP
   ${MQT_QMAP_TARGET_NAME}-clifford_synthesis-bindings
   clifford_synthesis.cpp
@@ -16,8 +16,7 @@ add_mqt_python_binding(
   .
   LINK_LIBS
   MQT::QMapCliffordSynthesis
-  MQT::CoreQASM
-  pybind11_json)
+  MQT::CoreQASM)
 
 # install the Python stub files in editable mode for better IDE support
 if(SKBUILD_STATE STREQUAL "editable")

bindings/hybrid_mapper/CMakeLists.txt

@@ -6,7 +6,7 @@
 #
 # Licensed under the MIT License
 
-add_mqt_python_binding(
+add_mqt_python_binding_nanobind(
   QMAP
   ${MQT_QMAP_TARGET_NAME}-hybrid_mapper-bindings
   hybrid_mapper.cpp
@@ -16,8 +16,7 @@ add_mqt_python_binding(
   .
   LINK_LIBS
   MQT::QMapHybrid
-  MQT::CoreQASM
-  pybind11_json)
+  MQT::CoreQASM)
 
 # install the Python stub files in editable mode for better IDE support
 if(SKBUILD_STATE STREQUAL "editable")