Skip to content

doc: Pin pip to <25.3 for RTD as a workaround for pybind in admin/doc-read-the-docs.txt#66059

Merged
dmick merged 1 commit intoceph:mainfrom
bluikko:doc-fix-rtd-pip-version
Oct 29, 2025
Merged

doc: Pin pip to <25.3 for RTD as a workaround for pybind in admin/doc-read-the-docs.txt#66059
dmick merged 1 commit intoceph:mainfrom
bluikko:doc-fix-rtd-pip-version

Conversation

@bluikko
Copy link
Contributor

@bluikko bluikko commented Oct 25, 2025 •
edited
Loading

Readthedocs now uses pip 25.3 by default which requires PEP 517. src/pybind/* does not provide pyproject.toml files for PEP 517.
For an immediate workaround to allow RTD builds to succeed, pin pip version to earlier than 25.3.

Details for pybind in https://tracker.ceph.com/issues/73645

Example error from RTD build in https://app.readthedocs.org/projects/ceph/builds/30075240/ using the default pip 25.3:

	python -m pip install --upgrade --no-cache-dir pip setuptools 
Requirement already satisfied: pip in /home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/66058/lib/python3.9/site-packages (23.1)
Collecting pip
  Downloading pip-25.3-py3-none-any.whl (1.8 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.8/1.8 MB 15.0 MB/s eta 0:00:00
Requirement already satisfied: setuptools in /home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/66058/lib/python3.9/site-packages (67.6.1)
Collecting setuptools
  Downloading setuptools-80.9.0-py3-none-any.whl (1.2 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.2/1.2 MB 22.2 MB/s eta 0:00:00
Installing collected packages: setuptools, pip
  Attempting uninstall: setuptools
    Found existing installation: setuptools 67.6.1
    Uninstalling setuptools-67.6.1:
      Successfully uninstalled setuptools-67.6.1
  Attempting uninstall: pip
    Found existing installation: pip 23.1
    Uninstalling pip-23.1:
      Successfully uninstalled pip-23.1
Successfully installed pip-25.3 setuptools-80.9.0

...

python -m pip install --exists-action=w --no-cache-dir -r admin/doc-pybind.txt  
Processing ./src/pybind/rados
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: started
  Getting requirements to build wheel: finished with status 'error'
  error: subprocess-exited-with-error
  
  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [2 lines of output]
      ERROR: Cannot find Cythonized file rados.c
      WARNING: Cython is not installed.
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed to build 'file:///home/docs/checkouts/readthedocs.org/user_builds/ceph/checkouts/66058/src/pybind/rados' when getting requirements to build wheel

A warning from any build that used to succeed with pip 25.2 that was the default on RTD until today:

DEPRECATION: Building 'rados' using the legacy setup.py bdist_wheel mechanism, which will be removed in a future version. pip 25.3 will enforce this behaviour change. A possible replacement is to use the standardized build interface by setting the --use-pep517 option, (possibly combined with --no-build-isolation), or adding a pyproject.toml file to the source tree of 'rados'. Discussion can be found at pypa/pip#6334

Contribution Guidelines

  • To sign and title your commits, please refer to Submitting Patches to Ceph.

  • If you are submitting a fix for a stable branch (e.g. "quincy"), please refer to Submitting Patches to Ceph - Backports for the proper workflow.

  • When filling out the below checklist, you may click boxes directly in the GitHub web UI. When entering or editing the entire PR message in the GitHub web UI editor, you may also select a checklist item by adding an x between the brackets: [x]. Spaces and capitalization matter when checking off items this way.

Checklist

  • Tracker (select at least one)
    • References tracker ticket
    • Very recent bug; references commit where it was introduced
    • New feature (ticket optional)
    • Doc update (no ticket needed)
    • Code cleanup (no ticket needed)
  • Component impact
    • Affects Dashboard, opened tracker ticket
    • Affects Orchestrator, opened tracker ticket
    • No impact that needs to be tracked
  • Documentation (select at least one)
    • Updates relevant documentation
    • No doc update is appropriate
  • Tests (select at least one)
Show available Jenkins commands

You must only issue one Jenkins command per-comment. Jenkins does not understand
comments with more than one command.

@bluikko
doc: Pin pip to <25.3 for RTD as a workaround for pybind
a65c46c 
Readthedocs now uses pip 25.3 by default which requires PEP 517.
src/pybind/* does not provide pyproject.toml files for PEP 517.
For an immediate workaround to allow RTD builds to succeed, pin pip
version to earlier than 25.3.

Details for pybind in https://tracker.ceph.com/issues/73645

Signed-off-by: Ville Ojamo <14869000+bluikko@users.noreply.github.com>
@bluikko bluikko changed the title admin: Pin pip to <25.3 for RTD as a workaround for pybind in doc-read-the-docs.txt doc: Pin pip to <25.3 for RTD as a workaround for pybind in doc-read-the-docs.txt Oct 25, 2025
@bluikko bluikko changed the title doc: Pin pip to <25.3 for RTD as a workaround for pybind in doc-read-the-docs.txt doc: Pin pip to <25.3 for RTD as a workaround for pybind in admin/doc-read-the-docs.txt Oct 25, 2025
@bluikko bluikko force-pushed the doc-fix-rtd-pip-version branch from 1df74af to a65c46c Compare October 25, 2025 08:37
@bluikko bluikko mentioned this pull request Oct 25, 2025
Closed
14 tasks
@bluikko
Copy link
Contributor Author

bluikko commented Oct 25, 2025

Changed the commit & PR title to start with doc: instead of admin: as per the failing Signed-off-by job output.

With this PR Readthedocs build now downgrades pip from the default 25.3 to 25.2 before the src/pybind/* jobs and RTD succeeds.

@bluikko bluikko marked this pull request as ready for review October 25, 2025 08:44
phlogistonjohn
phlogistonjohn approved these changes Oct 28, 2025
View reviewed changes
Copy link
Contributor

@phlogistonjohn phlogistonjohn left a comment

Choose a reason for hiding this comment

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

looks ok for a workaround.

Do you have any thoughts on a longer term approach?

@bluikko
Copy link
Contributor Author

bluikko commented Oct 28, 2025

looks ok for a workaround.

Do you have any thoughts on a longer term approach?

pip 25.3 seems to indicate that it wants the PEP 517 pyproject.toml files in src/pybind/*. I've not looked into what exactly that would entail because PEP 517 & PEP 518 are rather long.

@phlogistonjohn
Copy link
Contributor

phlogistonjohn commented Oct 28, 2025

Fair enough, thanks.

@bluikko
Copy link
Contributor Author

bluikko commented Oct 29, 2025 •
edited
Loading

Fair enough, thanks.

To be clear: I have not looked into adding those files because I do not know if that's a good direction or there could be some other long-term solution. If PEP 517 compatibility is judged to be a good long-term solution and nobody else is familiar with the syntax of these files then I can look into how to do it.

@dmick dmick merged commit 211482f into ceph:main Oct 29, 2025
16 checks passed
@djgalloway djgalloway mentioned this pull request Oct 29, 2025
Merged
This was referenced Nov 3, 2025
Merged
Merged
Merged
@Matan-B Matan-B mentioned this pull request Nov 5, 2025
Merged
14 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dmick dmick dmick approved these changes

@phlogistonjohn phlogistonjohn phlogistonjohn approved these changes

Assignees

No one assigned

Labels

build/ops script

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@bluikko @phlogistonjohn @dmick