Skip to content

gh-88130: Document macOS library search limits for ctypes.CDLL - #161624

Open
mesubash wants to merge 1 commit into
python:mainfrom
mesubash:gh-88130-ctypes-macos-docs
Open

mesubash wants to merge 1 commit into
python:mainfrom
mesubash:gh-88130-ctypes-macos-docs

Conversation

@mesubash

@mesubash mesubash commented Nov 8, 2026 •

Copy link
Copy Markdown

On macOS, CDLL with a relative name may only search system locations such as /usr/lib, so libraries in /usr/local/lib, ~/lib or ~/Library/Frameworks are not found. This adds a short note under CDLL saying to pass the full path, and that DYLD_LIBRARY_PATH / DYLD_FRAMEWORK_PATH help only for some executables.

The test results behind each sentence are in my comment on the issue: #88130 (comment)

I left out find_library(). It found the library in every test, but the docs call it soft deprecated. Happy to add a mention if you think it belongs here.

Copilot AI balanced review requested due to automatic review settings November 8, 2026 16:29
@python-cla-bot

python-cla-bot Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.

CLA signed

@bedevere-app bedevere-app Bot added awaiting review docs Documentation in the Doc dir labels Nov 8, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35735913 | 📁 Comparing 01c97fb against main (7271803)

  🔍 Preview build  

2 files changed
± library/ctypes.html
± whatsnew/changelog.html

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs-only changes don't need changelog entries, so please remove this.

(This blurb section is badly named, sorry! It's meant for changes to the build script and such.)

Comment thread Doc/library/ctypes.rst
Comment on lines +1587 to +1593
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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with Petr that we should be more explicit about the fact that ctypes.CDLL calls dlopen, and thus inherits any quirks from the system-level function. Once we've done that, I'm not sure it's necessary to document all the individual quirks of what a given OS does.

@bedevere-app

bedevere-app Bot commented Nov 11, 2026

Copy link
Copy Markdown

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting changes docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

4 participants