readthedocs.org: Could not import extension sphinx.builders.linkcheck (exception: urllib3 v2.0 only supports OpenSSL 1.1.1+)

More specifically, you should use a configuration file that that specifies the build OS.

That is, add a .readthedocs.yaml file in your repository root:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

This will ensure you are not using one of the older images.

Edit: updated to mention build.tools

@stsewd I suspect this issue will get a lot of traffic, if possible could the correct answer w/ example of upgrading to build.os: ubuntu-22.04 instead of pinning urllib3 be elevated to the first reply. I suspect folks may be looking for quick solutions to this incompatibility and I’d like people to keep urllib3 unpinned if it’s not blocked by anything else in their environment.

Hi, this is because urlib3 was released yesterday, and that version isn’t compatible with the docker image you are using. To use a more recent version of our docker images, please use a config file (https://docs.readthedocs.io/en/stable/config-file/v2.html), or pin urllib3 in your requirements to a previous version.

Edit: projects should use a configuration file and leave urllib3 unpinned

Hi! Thank you all for reporting this issue and for your patience 😄 .

TLDR; new Docker images with SSL 1.1.1 were deployed and they are ready to use. If your project was failing because of this, it should not be failing anymore. If you still have this problem or you find another one that looks related to the rebuild of the images, please open a new issue.

Here I’m writing down the news about this problem:

The root cause

Read the Docs still supports some old Docker images [^1] that contains Python versions compiled with SSL 1.0.x and this SSL version was dropped support from urlib3 in its latest release. urllib3 is used by requests behind the scenes and requests is used by a lot of things; in particular Sphinx linkcheck command where this was originally found.

The workaround

Upgrade your .yaml file to use build.os: ubuntu-22.04 as mentioned in https://github.com/readthedocs/readthedocs.org/issues/10290#issuecomment-1535120995

Besides being a workaround, this upgrade is useful to be up-to-date with the latest version of the RTD config file, which introduces you to some nice features like build customization

The solution

We re-built the Docker images so they use SSL 1.1.1 to compile the Python versions via pyenv. This should be transparent for all the projects and they should not notice any new error, 🤞🏼

The future

SSL 1.1.1 is gonna be unsupported later this year as well, based on https://github.com/urllib3/urllib3/issues/2168; so, we are thinking about deprecating and removing these Docker images (and the whole build.image key) completely before that time. We need to keep talking about this and how to do it without breaking lot of projects.

[^1]: this is build.image key in the config file with any of the values stable, latest and testing. A lot of users were hitting this because build.image: latest with Python 3.7 is still the default; but we are working on changing this default to a more up-to-date version of Ubuntu and Python as well. Please, if you are using build.image in your .yaml file, upgrade it to build.os: ubuntu-22.04 as mentioned in https://github.com/readthedocs/readthedocs.org/issues/10290#issuecomment-1535120995

If another poor soul is here from using the readthedocs template, here’s what worked for me.

Add the .readthedocs.yaml at the root of your repo. Note the docs/source/conf.py, which can be easily overlooked from the config file example.

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
    # You can also specify other tool versions:
    # nodejs: "19"
    # rust: "1.64"
    # golang: "1.19"

# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/source/conf.py

# If using Sphinx, optionally build your docs in additional formats such as PDF
# formats:
#    - pdf

# Optionally declare the Python requirements required to build your docs
# python:
#  install:
#   - requirements: docs/requirements.txt

Also, I opened an issue yesterday for updating and fixing the legacy build image: https://github.com/readthedocs/readthedocs-docker-images/issues/194

We’ll track updating and fixing the image there. I’ll see what I can do today and tomorrow

@stereoshoots check your build output for errors/warning in the Sphinx build command. The upgrade to the operating system image also means there were a number of dependencies changed in the process.

@RemDelaporteMathurin it’s not just version: 2 that is required to avoid the bug here, but specifically build.os: ubuntu-22.04.

@sethmlarson Thanks for the note, I’d agree the configuration fix should be the recommended fix. I’ll edit the guidance above.

It seems like we’re probably going to aim to get some sort of fix out here, as this is causing a bit of trouble for folks. It seems the trouble is an old pyenv compiled Python in an image we’re trying to deprecate, but should be something we can fix.

Unfortunately, we’re going into Write the Docs conference time, so we haven’t settled on a timeframe yet.

We haven’t heard people hitting any new issue after the deploy with the fix we did yesterday; so I’m going to close this issue.

If you are arrive at this issue by browsing the internet, please refer to this comment in particular #10290 (comment)

Thanks you all for the support! ❤️

I was having this error for at least 2 days. Now I was able to compile the documentation without any problems. Looks like fixed. Great!

We haven’t heard people hitting any new issue after the deploy with the fix we did yesterday; so I’m going to close this issue.

If you are arrive at this issue by browsing the internet, please refer to this comment in particular https://github.com/readthedocs/readthedocs.org/issues/10290#issuecomment-1542841524

Thanks you all for the support! ❤️

@BeyondEvil it’s still recommended general to use an automated process to explicitly pin all of your direct and transitive dependencies.

But on the other hand, I wouldn’t recommend that solution as a fix here either. This requires additional tooling like pip-tools to automate. For the basic user, the direct fix above is the easiest first step, but defining dependencies explicitly is a great idea still

@BeyondEvil Correct! If you do add a pinned dependency your project should indeed be okay, especially if you have followed the guide for reproducible builds.

Thanks @mmmarinho! You saved my day! I didn’t realise it was docs/conf.py and notdocs/source/conf.py