We are announcing the deprecation of python.install.method: setuptools in the .readthedocs.yaml configuration file.

This option uses python setup.py install, which is deprecated in the Python packaging ecosystem. Read the Docs will remove support for it on Wednesday, July 1st, 2026. After this date, projects still using python.install.method: setuptools will fail their builds until they are updated.

Projects using this install method will have a configuration file that looks like this:

version: 2

python:
  install:
    - method: setuptools
      path: .

These projects should update their configuration file to use pip instead:

version: 2

python:
  install:
    - method: pip
      path: .

If you are already using python.install.method: pip, python.install.method: uv, or you are not using method: setuptools, no action is required.

pip is the recommended replacement for most projects. If you are using uv for your Python dependency management, you can also migrate to python.install.method: uv.

Deprecation timeline

• Tuesday, April 21, 2026: Publish this deprecation announcement.
• Before Wednesday, July 1, 2026: Email maintainers of active projects that are still using python.install.method: setuptools.
• Wednesday, July 1, 2026: Remove support for python.install.method: setuptools on Read the Docs.

How to update your project

For most projects, replacing method: setuptools with method: pip is enough. This changes the installation step from python setup.py install to pip install, which is the supported and recommended workflow.

If your project installs optional dependencies, you can keep using extra_requirements with pip:

version: 2

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

Projects that only install requirements files and do not use python.install.method: setuptools are not affected by this change.

Contact us

Contact us if you have any questions, or if you run into issues migrating away from python.install.method: setuptools.