Use build.os instead of build.image on your configuration file

We are announcing the deprecation of build.image config key in favor of build.os. Read the Docs will start requiring a build.os config key for all projects in order to build documentation successfully. We will start failing builds for projects not using “build.os” in their config file on October 16, 2023.

Deprecation timeline

We understand this change will affect many of our users, so we have a timeline to communicate this deprecation to our users effectively.

  • Monday, August 28, 2023: Do the first brownout (temporarily enforce this deprecation) for 12 hours: 00:01 PST to 11:59 PST (noon)

  • Monday, September 18, 2023: Do a second brownout (temporarily enforce this deprecation) for 24 hours: 00:01 PST to 23:59 PST (midnight)

  • Monday, October 2, 2023: Do a third and final brownout (temporarily enforce this deprecation) for 48 hours: 00:01 PST to October 3, 2023 23:59 PST (midnight)

  • Monday, October 16, 2023: Fully remove support for building documentation using “build.image” on the configuration file

Migrating to build.os

If you have a project on Read the Docs that is not using build.os, you will need to migrate to the new config key as soon as possible to continue building your project.

There are some small differences between build.image and build.os that we detail here:

  • version: 2 must be used with build.os

  • To specify the Python version, you have to use

Below is an example of a valid build section of your configuration. Make sure to make these changes before October 16, 2023:

version: 2
  os: "ubuntu-22.04"
    python: "3.11"

You can read about the build.os key, including all possible values, in our “build” configuration documentation.

Contact us

Contact us if you have any questions, and let us know if you are having trouble using a this new config key for any reason.