Configuration file v2 (.readthedocs.yaml)

Read the Docs supports configuring your documentation builds with a configuration file. This file is named .readthedocs.yaml and should be placed in the top level of your Git repository.

The .readthedocs.yaml file can contain a number of settings that are not accessible through the Read the Docs website.

Because the file is stored in Git, the configuration will apply to the exact version that is being built. This allows you to store different configurations for different versions of your documentation.

Below is an example YAML file which shows the most common configuration options:

.readthedocs.yaml

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

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
    # You can also specify other tool versions:
    # nodejs: "20"
    # rust: "1.70"
    # golang: "1.20"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
  configuration: docs/conf.py
  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
  # builder: "dirhtml"
  # Fail on all warnings to avoid broken references
  # fail_on_warning: true

# Optionally build your docs in additional formats such as PDF and ePub
# formats:
#    - pdf
#    - epub

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
# python:
#    install:
#    - requirements: docs/requirements.txt

.readthedocs.yaml

# Read the Docs configuration file for MkDocs projects
# 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"

mkdocs:
  configuration: mkdocs.yml

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

Supported settings

Read the Docs validates every configuration file. Any configuration option that isn’t supported will make the build fail. This is to avoid typos and provide feedback on invalid configurations.

Warning

When using a v2 configuration file, the local settings from the web interface are ignored.

version 

Required:: true

Example:

version: 2

Warning

If you don’t provide the version, v1 will be used.

formats 

Additional formats of the documentation to be built, apart from the default HTML.

Type:: list
Options:: htmlzip, pdf, epub, all
Default:: []

Example:

version: 2

# Default
formats: []

version: 2

# Build PDF & ePub
formats:
  - epub
  - pdf

Note

You can use the all keyword to indicate all formats.

version: 2

# Build all formats
formats: all

Warning

At the moment, only Sphinx supports additional formats. pdf, epub, and htmlzip output is not yet supported when using MkDocs.

With builds from pull requests, only HTML formats are generated. Other formats are resource intensive and will be built after merging.

python 

Configuration of the Python environment to be used.

version: 2

python:
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .
      extra_requirements:
        - docs
    - method: pip
      path: another/package

python.version 

Warning

This option is now deprecated and replaced by build.tools.python. See python.version (legacy) for the description of this option.

python.install 

List of installation methods of packages and requirements. You can have several of the following methods.

Type:: list
Default:: []

Requirements file 

Install packages from a requirements file.

The path to the requirements file, relative to the root of the project.

Key:: requirements
Type:: path
Required:: false

Example:

version: 2

python:
  install:
    - requirements: docs/requirements.txt
    - requirements: requirements.txt

Warning

If you are using a Conda environment to manage the build, this setting will not have any effect. Instead add the extra requirements to the environment file of Conda.

Packages 

Install the project using pip install (recommended) or python setup.py install (deprecated).

The path to the package, relative to the root of the project.

Key:: path
Type:: path
Required:: false

The installation method.

Key:: method
Options:: pip, setuptools (deprecated)
Default:: pip

Extra requirements section to install in addition to the package dependencies.

Warning

You need to install your project with pip to use extra_requirements.

Key:: extra_requirements
Type:: list
Default:: []

Example:

version: 2

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

With the previous settings, Read the Docs will execute the next commands:

pip install .[docs]

conda 

Configuration for Conda support.

version: 2

build:
  os: "ubuntu-22.04"
  tools:
    python: "mambaforge-22.9"

conda:
  environment: environment.yml

conda.environment 

The path to the Conda environment file, relative to the root of the project.

Type:: path
Required:: false

Note

When using Conda, it’s required to specify build.tools.python to tell Read the Docs to use whether Conda or Mamba to create the environment.

build 

Configuration for the documentation build process. This allows you to specify the base Read the Docs image used to build the documentation, and control the versions of several tools: Python, Node.js, Rust, and Go.

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
    nodejs: "18"
    rust: "1.64"
    golang: "1.19"

build.os 

The Docker image used for building the docs. Image names refer to the operating system Read the Docs uses to build them.

Note

Arbitrary Docker images are not supported.

Type:: string
Options:: ubuntu-20.04, ubuntu-22.04
Required:: true

build.tools 

Version specifiers for each tool. It must contain at least one tool.

Type:: dict
Options:: python, nodejs, rust, golang
Required:: true

build.tools.python 

Python version to use. You can use several interpreters and versions, from CPython, Miniconda, and Mamba.

Note

If you use Miniconda3 or Mambaforge, you can select the Python version using the environment.yml file. See our How to use Conda as your Python environment guide for more information.

Type:

string

Options:

2.7
3 (last stable CPython version)
3.6
3.7
3.8
3.9
3.10
3.11
miniconda3-4.7
mambaforge-4.10
mambaforge-22.9

build.tools.nodejs 

Node.js version to use.

Type:

string

Options:

14
16
18
19
20

build.tools.rust 

Rust version to use.

Type:

string

Options:

1.55
1.61
1.64
1.70

build.tools.golang 

Go version to use.

Type:

string

Options:

1.17
1.18
1.19
1.20

build.apt_packages 

List of APT packages to install. Our build servers run Ubuntu 18.04, with the default set of package repositories installed. We don’t currently support PPA’s or other custom repositories.

Type:: list
Default:: []

version: 2

build:
  apt_packages:
    - libclang
    - cmake

Note

When possible avoid installing Python packages using apt (python3-numpy for example), use pip or conda instead.

Warning

Currently, it’s not possible to use this option when using build.commands.

build.jobs 

Commands to be run before or after a Read the Docs pre-defined build jobs. This allows you to run custom commands at a particular moment in the build process. See Build process customization for more details.

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  jobs:
    pre_create_environment:
      - echo "Command run at 'pre_create_environment' step"
    post_build:
      - echo "Command run at 'post_build' step"
      - echo `date`

Note

Each key under build.jobs must be a list of strings. build.os and build.tools are also required to use build.jobs.

Type:: dict
Allowed keys:: post_checkout, pre_system_dependencies, post_system_dependencies, pre_create_environment, post_create_environment, pre_install, post_install, pre_build, post_build
Required:: false
Default:: {}

build.commands 

Specify a list of commands that Read the Docs will run on the build process. When build.commands is used, none of the pre-defined build jobs will be executed. (see Build process customization for more details). This allows you to run custom commands and control the build process completely. The $READTHEDOCS_OUTPUT/html directory will be uploaded and hosted by Read the Docs.

Warning

This feature is in a beta phase and could suffer incompatible changes or even removed completely in the near feature. We are currently testing the new addons integrations we are building on projects using build.commands configuration key. Use it under your own responsibility.

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  commands:
    - pip install pelican
    - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

Note

build.os and build.tools are also required when using build.commands.

Type:: list
Required:: false
Default:: []

sphinx 

Configuration for Sphinx documentation (this is the default documentation type).

version: 2

sphinx:
  builder: html
  configuration: conf.py
  fail_on_warning: true

Note

If you want to pin Sphinx to a specific version, use a requirements.txt or environment.yml file (see Requirements file and conda.environment). If you are using a metadata file to describe code dependencies like setup.py, pyproject.toml, or similar, you can use the extra_requirements option (see Packages). This also allows you to override the default pinning done by Read the Docs if your project was created before October 2020.

sphinx.builder 

The builder type for the Sphinx documentation.

Type:: string
Options:: html, dirhtml, singlehtml
Default:: html

Note

The htmldir builder option was renamed to dirhtml to use the same name as sphinx. Configurations using the old name will continue working.

sphinx.configuration 

The path to the conf.py file, relative to the root of the project.

Type:: path
Default:: null

If the value is null, Read the Docs will try to find a conf.py file in your project.

sphinx.fail_on_warning 

Turn warnings into errors (-W and --keep-going options). This means the build fails if there is a warning and exits with exit status 1.

Type:: bool
Default:: false

mkdocs 

Configuration for MkDocs documentation.

version: 2

mkdocs:
  configuration: mkdocs.yml
  fail_on_warning: false

Note

If you want to pin MkDocs to a specific version, use a requirements.txt or environment.yml file (see Requirements file and conda.environment). If you are using a metadata file to describe code dependencies like setup.py, pyproject.toml, or similar, you can use the extra_requirements option (see Packages). This also allows you to override the default pinning done by Read the Docs if your project was created before March 2021.

mkdocs.configuration 

The path to the mkdocs.yml file, relative to the root of the project.

Type:: path
Default:: null

If the value is null, Read the Docs will try to find a mkdocs.yml file in your project.

mkdocs.fail_on_warning 

Turn warnings into errors. This means that the build stops at the first warning and exits with exit status 1.

Type:: bool
Default:: false

submodules 

VCS submodules configuration.

Note

Only Git is supported at the moment.

Warning

You can’t use include and exclude settings for submodules at the same time.

version: 2

submodules:
  include:
    - one
    - two
  recursive: true

submodules.include 

List of submodules to be included.

Type:: list
Default:: []

Note

You can use the all keyword to include all submodules.

version: 2

submodules:
  include: all

submodules.exclude 

List of submodules to be excluded.

Type:: list
Default:: []

Note

You can use the all keyword to exclude all submodules. This is the same as include: [].

version: 2

submodules:
  exclude: all

submodules.recursive 

Do a recursive clone of the submodules.

Type:: bool
Default:: false

Note

This is ignored if there aren’t submodules to clone.

search 

Settings for more control over Server side search.

version: 2

search:
  ranking:
    api/v1/*: -1
    api/v2/*: 4
  ignore:
    - 404.html

search.ranking 

Set a custom search rank over pages matching a pattern.

Type:: map of patterns to ranks
Default:: {}

Patterns are matched against the final html pages produced by the build (you should try to match index.html, not docs/index.rst). Patterns can include some special characters:

* matches everything
? matches any single character
[seq] matches any character in seq

The rank can be an integer number between -10 and 10 (inclusive). Pages with a rank closer to -10 will appear further down the list of results, and pages with a rank closer to 10 will appear higher in the list of results. Note that 0 means normal rank, not no rank.

If you are looking to completely ignore a page, check search.ignore.

version: 2

search:
  ranking:
    # Match a single file
    tutorial.html: 2

    # Match all files under the api/v1 directory
    api/v1/*: -5

    # Match all files that end with tutorial.html
    '*/tutorial.html': 3

Note

The final rank will be the last pattern to match the page.

Tip

Is better to decrease the rank of pages you want to deprecate, rather than increasing the rank of the other pages.

search.ignore 

List of paths to ignore and exclude from the search index. Paths matched will not be included in search results.

Type:: list of patterns
Default:: ['search.html', 'search/index.html', '404.html', '404/index.html']

Patterns are matched against the relative path of html files produced by the build (you should try to match index.html, not docs/index.rst). Patterns can include some special characters:

* matches everything
? matches any single character
[seq] matches any character in seq

version: 2

search:
   ignore:
     # Ignore a single file in the root of the output directory
     - 404.html

     # Ignore all files under the search/ directory
     - search/*

     # Ignore all files named ref.html nested inside one or more sub-folders
     - '*/ref.html'

version: 2

search:
   ignore:
     # Custom files to ignore
     - file.html
     - api/v1/*

     # Defaults
     - search.html
     - search/index.html
     - 404.html
     - 404/index.html'

Note

Since Read the Docs fallbacks to the original search engine when no results are found, you may still see search results from ignored pages.

Schema

You can see the complete schema here. This schema is available at Schema Store, use it with your favorite editor for validation and autocompletion.

Legacy `build` specification

The legacy build specification used a different set of Docker images, and only allowed you to specify the Python version. It remains supported for backwards compatibility reasons. Check out the build above for an alternative method that is more flexible.

version: 2

build:
  image: latest
  apt_packages:
    - libclang
    - cmake

python:
  version: "3.7"

The legacy build specification also supports the apt_packages key described above.

Warning

When using the new specification, the build.image and python.version options cannot be used. Doing so will error the build.

build (legacy)

build.image (legacy)

The Docker image used for building the docs.

Type:: string
Options:: stable, latest
Default:: latest

Each image support different Python versions and has different packages installed, as defined here:

stable: 2, 2.7, 3, 3.5, 3.6, 3.7
latest: 2, 2.7, 3, 3.5, 3.6, 3.7, 3.8

python.version (legacy)

The Python version (this depends on build.image (legacy)).

Type:: string
Default:: 3

Note

Make sure to use quotes (") to make it a string. We previously supported using numbers here, but that approach is deprecated.

Warning

If you are using a Conda environment to manage the build, this setting will not have any effect, as the Python version is managed by Conda.

Migrating from v1

Changes

The version setting is required. See version.
The default value of the formats setting has changed to [] and it doesn’t include the values from the web interface.
The top setting requirements_file was moved to python.install and we don’t try to find a requirements file if the option isn’t present. See Requirements file.
The setting conda.file was renamed to conda.environment. See conda.environment.
The build.image setting has been replaced by build.os. See build.os. Alternatively, you can use the legacy build.image that now has only two options: latest (default) and stable.
The settings python.setup_py_install and python.pip_install were replaced by python.install. And now it accepts a path to the package. See Packages.
The build will fail if there are invalid keys (strict mode).

Warning

Some values from the web interface are no longer respected, please see Migrating from the web interface if you have settings there.

Migrating from the web interface

This should be pretty straightforward, just go to the Admin > Advanced settings, and find their respective setting in here.

Not all settings in the web interface are per version, but are per project. These settings aren’t supported via the configuration file.

Name
Repository URL
Repository type
Language
Programming language
Project homepage
Tags
Single version
Default branch
Default version
Show versions warning
Privacy level
Analytics code

Custom paths for .readthedocs.yaml

In order to support monorepo layouts, it’s possible to configure the path to where your .readthedocs.yaml is found.

Using this configuration makes it possible to create several Read the Docs projects pointing at the same Git repository. This is recommended for monorepo layouts that host several documentation projects in the same repository.

Previous version: v1

Version 1 is deprecated and using it is discouraged, view its reference here Configuration file v1 (Deprecated).

Configuration file v2 (.readthedocs.yaml)

Supported settings

Schema

Legacy build specification

build (legacy)

build.image (legacy)

python.version (legacy)

Migrating from v1

Changes

New settings

Migrating from the web interface

Custom paths for .readthedocs.yaml

Previous version: v1

Legacy `build` specification