feat!: drop support for Python 3.8, MSVC 2017

.appveyor.yml

@@ -1,6 +1,6 @@
 version: 1.0.{build}
 image:
-- Visual Studio 2017
+- Visual Studio 2019
 test: off
 skip_branch_with_pr: true
 build:
@@ -9,21 +9,36 @@ platform:
 - x86
 environment:
   matrix:
-  - PYTHON: 38
+  - PYTHON: 39
     CONFIG: Debug
 install:
 - ps: |
-    $env:CMAKE_GENERATOR = "Visual Studio 15 2017"
-    if ($env:PLATFORM -eq "x64") { $env:PYTHON = "$env:PYTHON-x64" }
-    $env:PATH = "C:\Python$env:PYTHON\;C:\Python$env:PYTHON\Scripts\;$env:PATH"
+    $env:CMAKE_GENERATOR = "Visual Studio 16 2019"
+    # The 2019 generator defaults to x64, so name the architecture explicitly.
+    if ($env:PLATFORM -eq "x64") {
+      $env:PYTHON = "$env:PYTHON-x64"
+      $env:CMAKE_ARCH = "x64"
+    } else {
+      $env:CMAKE_ARCH = "Win32"
+    }
+    $env:PYTHON_ROOT = "C:\Python$env:PYTHON"
+    $env:PATH = "$env:PYTHON_ROOT\;$env:PYTHON_ROOT\Scripts\;$env:PATH"
     python -W ignore -m pip install --upgrade pip wheel
     python -W ignore -m pip install pytest numpy --no-warn-script-location pytest-timeout
 - ps: |
     Start-FileDownload 'https://gitlab.com/libeigen/eigen/-/archive/3.3.7/eigen-3.3.7.zip'
     7z x eigen-3.3.7.zip -y > $null
     $env:CMAKE_INCLUDE_PATH = "eigen-3.3.7;$env:CMAKE_INCLUDE_PATH"
 build_script:
+# FindPython looks at the registry before PATH, so it picks the newest Python on
+# the image. Point it at the one that has the test packages.
+#
+# The image also has python39_d.lib, which FindPython uses for a Debug build.
+# pybind11 undefines _DEBUG around Python.h, so pyconfig.h asks for python39.lib
+# and the link fails. Take the release library in Debug too.
 - cmake -G "%CMAKE_GENERATOR%" -A "%CMAKE_ARCH%"
+    -DPython_ROOT_DIR="%PYTHON_ROOT%"
+    -DCMAKE_MAP_IMPORTED_CONFIG_DEBUG=Release
     -DCMAKE_CXX_STANDARD=14
     -DPYBIND11_WERROR=ON
     -DDOWNLOAD_CATCH=ON

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
       matrix:
         include:
           - runs-on: ubuntu-22.04
-            python-version: '3.8'
+            python-version: '3.9'
             cmake-args: -DPYBIND11_FINDPYTHON=OFF -DPYBIND11_NUMPY_1_ONLY=ON
           - runs-on: ubuntu-latest
             python-version: '3.13'
@@ -60,7 +60,7 @@ jobs:
             python-version: '3.14'
             cmake-args: -DCMAKE_CXX_STANDARD=14
           - runs-on: windows-2022
-            python-version: '3.8'
+            python-version: '3.9'
             cmake-args: -DPYBIND11_FINDPYTHON=OFF
 
 
@@ -78,7 +78,7 @@ jobs:
       matrix:
         include:
           - runs-on: ubuntu-latest
-            python-version: '3.8'
+            python-version: '3.9'
             cmake-args: -DPYBIND11_FINDPYTHON=ON -DCMAKE_CXX_STANDARD=17
           - runs-on: ubuntu-latest
             python-version: '3.10'
@@ -95,7 +95,7 @@ jobs:
 
           # No SciPy for macOS ARM
           - runs-on: macos-15-intel
-            python-version: '3.8'
+            python-version: '3.9'
             cmake-args: -DCMAKE_CXX_STANDARD=14
           - runs-on: macos-15-intel
             python-version: '3.13'
@@ -118,7 +118,7 @@ jobs:
             python-version: '3.9'
             cmake-args: -DPYBIND11_TEST_SMART_HOLDER=ON
           - runs-on: windows-2022
-            python-version: '3.8'
+            python-version: '3.9'
             cmake-args: -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded -DPYBIND11_NUMPY_1_ONLY=ON
           # This needs a python built with MTd
           # - runs-on: windows-2022
@@ -187,7 +187,7 @@ jobs:
     - name: Prepare env
       run: uv pip install --python=python --system -r tests/requirements.txt
 
-    # TODO Resolve Windows Ninja shared object issue on Python 3.8+
+    # TODO Resolve Windows Ninja shared object issue on Python 3.9+
     - name: Use Ninja except on Windows
       if: runner.os != 'Windows'
       run: echo "CMAKE_GENERATOR=Ninja" >> "$GITHUB_ENV"
@@ -629,9 +629,9 @@ jobs:
     - name: Latest actions/checkout
       uses: actions/checkout@v7
 
-    - name: Add Python 3.8
+    - name: Add Python 3.9
       if: matrix.container == 'almalinux:8'
-      run: dnf update -y && dnf install -y python38-devel gcc-c++ make git
+      run: dnf update -y && dnf install -y python39-devel gcc-c++ make git
 
     - name: Add Python 3 (default)
       if: matrix.container != 'almalinux:8'
@@ -767,7 +767,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - python: '3.8'
+          - python: '3.9'
             args: -DCMAKE_CXX_STANDARD=17
           - python: '3.13'
 

.github/workflows/pip.yml

@@ -19,16 +19,16 @@ jobs:
   # This builds the sdists and wheels and makes sure the files are exactly as
   # expected.
   test-packaging:
-    name: 🐍 3.8 • 📦 tests • windows-latest
+    name: 🐍 3.9 • 📦 tests • windows-latest
     runs-on: windows-latest
 
     steps:
     - uses: actions/checkout@v7
 
-    - name: Setup 🐍 3.8
+    - name: Setup 🐍 3.9
       uses: actions/setup-python@v6
       with:
-        python-version: 3.8
+        python-version: 3.9
 
     - name: Install uv
       uses: astral-sh/setup-uv@v8.2.0
@@ -43,16 +43,16 @@ jobs:
   # This runs the packaging tests and also builds and saves the packages as
   # artifacts.
   packaging:
-    name: 🐍 3.8 • 📦 & 📦 tests • ubuntu-latest
+    name: 🐍 3.9 • 📦 & 📦 tests • ubuntu-latest
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v7
 
-    - name: Setup 🐍 3.8
+    - name: Setup 🐍 3.9
       uses: actions/setup-python@v6
       with:
-        python-version: 3.8
+        python-version: 3.9
 
     - name: Install uv
       uses: astral-sh/setup-uv@v8.2.0

.github/workflows/reusable-standard.yml

@@ -63,7 +63,7 @@ jobs:
         if: runner.os == 'Linux'
         run: uv pip install --python=python --system pytest-github-actions-annotate-failures
 
-      # TODO Resolve Windows Ninja shared object issue on Python 3.8+
+      # TODO Resolve Windows Ninja shared object issue on Python 3.9+
       - name: Use Ninja except on Windows
         if: runner.os != 'Windows'
         run: echo "CMAKE_GENERATOR=Ninja" >> "$GITHUB_ENV"

AGENTS.md

@@ -95,5 +95,5 @@ Packaging produces two distributions: the normal `pybind11` (headers live inside
 - Any new functionality needs a test (add to or create the paired `.cpp`/`.py` in `tests/`, and register the test in `tests/CMakeLists.txt`).
 - Bug fixes should be paired with new tests that fail without the fix.
 - Try to add to an existing test file if possible (more files slow down tests)
-- Default C++ standard follows the consumer's toolchain; CI exercises a wide matrix (CPython 3.8+, PyPy, GraalPy; multiple compilers and C++ standards). Keep changes portable across that matrix.
+- Default C++ standard follows the consumer's toolchain; CI exercises a wide matrix (CPython 3.9+, PyPy, GraalPy; multiple compilers and C++ standards). Keep changes portable across that matrix.
 - PR descriptions follow a template, the key part is under "Suggested changelog entry", which is how we generate our changelog (with `nox -s make_changelog`)

README.rst

@@ -36,7 +36,7 @@ dependency.
 Think of this library as a tiny self-contained version of Boost.Python
 with everything stripped away that isn't relevant for binding
 generation. Without comments, the core header files only require ~4K
-lines of code and depend on Python (CPython 3.8+, PyPy, or GraalPy) and the C++
+lines of code and depend on Python (CPython 3.9+, PyPy, or GraalPy) and the C++
 standard library. This compact implementation was possible thanks to some C++11
 language features (specifically: tuples, lambda functions and variadic
 templates). Since its creation, this library has grown beyond Boost.Python in
@@ -81,7 +81,7 @@ Goodies
 In addition to the core functionality, pybind11 provides some extra
 goodies:
 
-- CPython 3.8+, PyPy3 7.3.17+, and GraalPy 24.1+ are supported with an
+- CPython 3.9+, PyPy3 7.3.17+, and GraalPy 24.1+ are supported with an
   implementation-agnostic interface (see older versions for older CPython
   and PyPy versions).
 

docs/advanced/classes.rst

@@ -1400,10 +1400,8 @@ You can do that using ``py::custom_type_setup``:
            auto *type = &heap_type->ht_type;
            type->tp_flags |= Py_TPFLAGS_HAVE_GC;
            type->tp_traverse = [](PyObject *self_base, visitproc visit, void *arg) {
-   // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
-   #if PY_VERSION_HEX >= 0x03090000
+               // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
                Py_VISIT(Py_TYPE(self_base));
-   #endif
                if (py::detail::is_holder_constructed(self_base)) {
                    auto &self = py::cast<ContainerOwnsPythonObjects &>(py::handle(self_base));
                    for (auto &item : self.list) {

docs/advanced/deprecated.rst

@@ -3,8 +3,6 @@
 Deprecated
 ##########
 
-Support for Python 3.8 is deprecated and will be removed in 3.1.
-
 Support for C++11 is deprecated and will be removed in a future version. Please
 use at least C++14.
 

docs/basics.rst

@@ -32,15 +32,14 @@ The last line will both compile and run the tests.
 Windows
 -------
 
-On Windows, only **Visual Studio 2017** and newer are supported.
+On Windows, only **Visual Studio 2019** and newer are supported.
 
 .. Note::
 
-    To use the C++17 in Visual Studio 2017 (MSVC 14.1), pybind11 requires the flag
-    ``/permissive-`` to be passed to the compiler `to enforce standard conformance`_. When
-    building with Visual Studio 2019, this is not strictly necessary, but still advised.
+    The ``/permissive-`` flag `to enforce standard conformance`_ is not necessary, but it is
+    still advised.
 
-..  _`to enforce standard conformance`: https://docs.microsoft.com/en-us/cpp/build/reference/permissive-standards-conformance?view=vs-2017
+..  _`to enforce standard conformance`: https://docs.microsoft.com/en-us/cpp/build/reference/permissive-standards-conformance
 
 To compile and run the tests:
 

docs/compiling.rst

@@ -429,7 +429,7 @@ with ``PYTHON_EXECUTABLE``.  For example:
 
 .. code-block:: bash
 
-    cmake -DPYBIND11_PYTHON_VERSION=3.8 ..
+    cmake -DPYBIND11_PYTHON_VERSION=3.9 ..
 
     # Another method:
     cmake -DPYTHON_EXECUTABLE=/path/to/python ..
@@ -495,7 +495,7 @@ FindPython, pybind11 will detect this and use the existing targets instead:
     cmake_minimum_required(VERSION 3.15...4.2)
     project(example LANGUAGES CXX)
 
-    find_package(Python 3.8 COMPONENTS Interpreter Development REQUIRED)
+    find_package(Python 3.9 COMPONENTS Interpreter Development REQUIRED)
     find_package(pybind11 CONFIG REQUIRED)
     # or add_subdirectory(pybind11)
 

include/pybind11/cast.h

@@ -2251,13 +2251,8 @@ class unpacking_collector {
         if (m_names) {
             nargs -= m_names.size();
         }
-        PyObject *result =
-#if PY_VERSION_HEX >= 0x03090000
-            PyObject_Vectorcall(
-#else
-            _PyObject_Vectorcall(
-#endif
-                ptr, m_args.data() + 1, nargs | PY_VECTORCALL_ARGUMENTS_OFFSET, m_names.ptr());
+        PyObject *result = PyObject_Vectorcall(
+            ptr, m_args.data() + 1, nargs | PY_VECTORCALL_ARGUMENTS_OFFSET, m_names.ptr());
         if (!result) {
             throw error_already_set();
         }

include/pybind11/detail/class.h

@@ -586,10 +586,8 @@ extern "C" inline int pybind11_traverse(PyObject *self, visitproc visit, void *a
     PyObject *&dict = *_PyObject_GetDictPtr(self);
     Py_VISIT(dict);
 #endif
-// https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
-#if PY_VERSION_HEX >= 0x03090000
+    // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
     Py_VISIT(Py_TYPE(self));
-#endif
     return 0;
 }
 

include/pybind11/detail/common.h

@@ -10,8 +10,8 @@
 #pragma once
 
 #include <pybind11/conduit/wrap_include_python_h.h>
-#if PY_VERSION_HEX < 0x03080000
-#    error "PYTHON < 3.8 IS UNSUPPORTED. pybind11 v2.13 was the last to support Python 3.7."
+#if PY_VERSION_HEX < 0x03090000
+#    error "PYTHON < 3.9 IS UNSUPPORTED. pybind11 v3.0 was the last to support Python 3.8."
 #endif
 
 // Similar to Python's convention: https://docs.python.org/3/c-api/apiabiversion.html
@@ -87,7 +87,7 @@
 #    endif
 #endif
 
-#if defined(__cpp_lib_launder) && !(defined(_MSC_VER) && (_MSC_VER < 1920)) // See PR #5968
+#if defined(__cpp_lib_launder)
 #    define PYBIND11_STD_LAUNDER std::launder
 #    define PYBIND11_HAS_STD_LAUNDER 1
 #else
@@ -132,8 +132,8 @@
 #        error pybind11 requires gcc 4.8 or newer
 #    endif
 #elif defined(_MSC_VER)
-#    if _MSC_VER < 1910
-#        error pybind11 2.10+ requires MSVC 2017 or newer
+#    if _MSC_VER < 1920
+#        error pybind11 3.1+ requires MSVC 2019 or newer
 #    endif
 #endif
 
@@ -826,7 +826,7 @@ using void_t = typename void_t_impl<Ts...>::type;
 #endif
 
 /// Compile-time all/any/none of that check the boolean value of all template types
-#if defined(__cpp_fold_expressions) && !(defined(_MSC_VER) && (_MSC_VER < 1916))
+#if defined(__cpp_fold_expressions)
 template <class... Ts>
 using all_of = bool_constant<(Ts::value && ...)>;
 template <class... Ts>
@@ -1357,7 +1357,7 @@ try_get_shared_from_this(std::enable_shared_from_this<T> *holder_value_ptr) {
 // Use at your own risk!
 // See also https://en.cppreference.com/w/cpp/memory/enable_shared_from_this, and in particular
 // the `std::shared_ptr<Good> gp1 = not_so_good.getptr();` and `try`-`catch` parts of the example.
-#if defined(__cpp_lib_enable_shared_from_this) && (!defined(_MSC_VER) || _MSC_VER >= 1912)
+#if defined(__cpp_lib_enable_shared_from_this)
     return holder_value_ptr->weak_from_this().lock();
 #else
     try {
@@ -1370,19 +1370,10 @@ try_get_shared_from_this(std::enable_shared_from_this<T> *holder_value_ptr) {
 
 // For silencing "unused" compiler warnings in special situations.
 template <typename... Args>
-#if defined(_MSC_VER) && _MSC_VER < 1920 // MSVC 2017
-constexpr
-#endif
-    inline void silence_unused_warnings(Args &&...) {
-}
+inline void silence_unused_warnings(Args &&...) {}
 
-// MSVC warning C4100: Unreferenced formal parameter
-#if defined(_MSC_VER) && _MSC_VER <= 1916
-#    define PYBIND11_WORKAROUND_INCORRECT_MSVC_C4100(...)                                         \
-        detail::silence_unused_warnings(__VA_ARGS__)
-#else
-#    define PYBIND11_WORKAROUND_INCORRECT_MSVC_C4100(...)
-#endif
+// MSVC warning C4100: Unreferenced formal parameter (only incorrect before MSVC 2019)
+#define PYBIND11_WORKAROUND_INCORRECT_MSVC_C4100(...)
 
 // GCC -Wunused-but-set-parameter  All GCC versions (as of July 2021).
 #if defined(__GNUG__) && !defined(__clang__) && !defined(__INTEL_COMPILER)

include/pybind11/detail/function_record_pyobject.h

@@ -48,8 +48,8 @@ static PyMethodDef tp_methods_impl[]
 // Python 3.12+ emits a DeprecationWarning for heap types whose tp_name does
 // not contain a dot ('.') and that lack a __module__ attribute. For pybind11's
 // internal function_record type, we do not have an actual module object to
-// attach, so we cannot use PyType_FromModuleAndSpec (introduced in Python 3.9)
-// to set __module__ automatically.
+// attach, so we cannot use PyType_FromModuleAndSpec to set __module__
+// automatically.
 //
 // As a workaround, we define a "qualified" type name that includes a dummy
 // module name (PYBIND11_DUMMY_MODULE_NAME). This is non‑idiomatic but avoids
@@ -59,8 +59,7 @@ static PyMethodDef tp_methods_impl[]
 //
 // even though no real pybind11_builtins module exists. If pybind11 gains an
 // actual module object in the future, this code should switch to
-// PyType_FromModuleAndSpec for Python 3.9+ and drop the dummy module
-// workaround.
+// PyType_FromModuleAndSpec and drop the dummy module workaround.
 //
 // Note that this name is versioned.
 #define PYBIND11_DETAIL_FUNCTION_RECORD_TP_PLAINNAME                                              \

include/pybind11/detail/type_caster_base.h

@@ -1133,7 +1133,7 @@ class type_caster_generic {
             if (type->operator_new) {
                 vptr = type->operator_new(type->type_size);
             } else {
-#if defined(__cpp_aligned_new) && (!defined(_MSC_VER) || _MSC_VER >= 1912)
+#if defined(__cpp_aligned_new)
                 if (type->type_align > __STDCPP_DEFAULT_NEW_ALIGNMENT__) {
                     vptr = ::operator new(type->type_size, std::align_val_t(type->type_align));
                 } else {