From 01c97fbab3eb2c2b1fa0a2fa1f28d41e97c365f9 Mon Sep 17 00:00:00 2001 From: Subash Singh Dhami Date: Sun, 8 Nov 2026 22:11:48 +0545 Subject: [PATCH 1/2] gh-88130: Document macOS library search limits for ctypes.CDLL --- Doc/library/ctypes.rst | 8 ++++++++ .../2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst | 2 ++ 2 files changed, 10 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 6f3524e0253bca..9ce441b09039c3 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1584,6 +1584,14 @@ way is to instantiate :py:class:`CDLL` or one of its subclasses: they are not added automatically. See :ref:`ctypes-finding-shared-libraries` for more information. + On macOS, a *name* that is not an absolute path may only be searched + for in system locations such as :file:`/usr/lib`. Libraries and + frameworks in folders like :file:`/usr/local/lib`, :file:`~/lib` or + :file:`~/Library/Frameworks` are then not found, so pass the full path. + Setting :envvar:`!DYLD_LIBRARY_PATH` or :envvar:`!DYLD_FRAMEWORK_PATH` + before starting Python adds search locations, but macOS ignores these + variables for some executables. + On non-Windows systems, *name* can be ``None``. In this case, :c:func:`!dlopen` is called with ``NULL``, which opens the main program as a "library". diff --git a/Misc/NEWS.d/next/Documentation/2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst b/Misc/NEWS.d/next/Documentation/2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst new file mode 100644 index 00000000000000..f5b923d05a73d6 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst @@ -0,0 +1,2 @@ +Document that :class:`ctypes.CDLL` on macOS may not find libraries in +:file:`/usr/local/lib` or user folders unless given a full path. From d727382bd518194134701fd6ac4e291e03cc66f8 Mon Sep 17 00:00:00 2001 From: Subash Singh Dhami Date: Mon, 16 Nov 2026 11:30:41 +0545 Subject: [PATCH 2/2] Address review: describe CDLL on macOS in terms of dlopen, drop NEWS entry --- Doc/library/ctypes.rst | 13 ++++++------- .../2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst | 2 -- 2 files changed, 6 insertions(+), 9 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 9ce441b09039c3..d5737ee9b85da2 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1584,13 +1584,12 @@ way is to instantiate :py:class:`CDLL` or one of its subclasses: they are not added automatically. See :ref:`ctypes-finding-shared-libraries` for more information. - On macOS, a *name* that is not an absolute path may only be searched - for in system locations such as :file:`/usr/lib`. Libraries and - frameworks in folders like :file:`/usr/local/lib`, :file:`~/lib` or - :file:`~/Library/Frameworks` are then not found, so pass the full path. - Setting :envvar:`!DYLD_LIBRARY_PATH` or :envvar:`!DYLD_FRAMEWORK_PATH` - before starting Python adds search locations, but macOS ignores these - variables for some executables. + On macOS, :class:`!CDLL` does no searching of its own: *name* is passed + to :c:func:`!dlopen`, so the search rules and notes in the macOS + ``dlopen`` manual page apply, including any changes in later macOS + releases. For example, with current builds of Python, including the + python.org installers, a *name* without a full path is not looked up in + :file:`/usr/local/lib`; pass the full path instead. On non-Windows systems, *name* can be ``None``. In this case, :c:func:`!dlopen` is called with ``NULL``, which opens the main program diff --git a/Misc/NEWS.d/next/Documentation/2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst b/Misc/NEWS.d/next/Documentation/2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst deleted file mode 100644 index f5b923d05a73d6..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2026-11-08-16-26-47.gh-issue-88130.JVOGb1.rst +++ /dev/null @@ -1,2 +0,0 @@ -Document that :class:`ctypes.CDLL` on macOS may not find libraries in -:file:`/usr/local/lib` or user folders unless given a full path.