Configuration file reference
============================

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.

.. note::

   When using a monorepo, it is possible to place the ``.readthedocs.yaml`` file
   in a subdirectory and configure a custom path from the project settings
   dashboard. All paths in the configuration file are always relative to the
   **repository root**, not the location of the configuration file.
   See the :doc:`/guides/setup/monorepo` documentation for more details.


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:

.. tabs::

   .. tab:: Sphinx

        .. literalinclude:: /config-file/examples/sphinx/.readthedocs.yaml
              :language: yaml
              :linenos:
              :caption: .readthedocs.yaml

   .. tab:: MkDocs

        .. literalinclude:: /config-file/examples/mkdocs/.readthedocs.yaml
           :language: yaml
           :linenos:
           :caption: .readthedocs.yaml


.. seealso::

   :doc:`/config-file/index`
      Practical steps to add a configuration file to your documentation project.


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.

.. contents::
   :local:
   :depth: 3

version
~~~~~~~

:Required: ``true``

Example:

.. code-block:: yaml

   version: 2

formats
~~~~~~~

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

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

Example:

.. code-block:: yaml

   version: 2

   # Default
   formats: []

.. code-block:: yaml

   version: 2

   # Build PDF & ePub
   formats:
     - epub
     - pdf

.. note::

   You can use the ``all`` keyword to indicate all formats.

   .. code-block:: yaml

      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.
   However, you can use :ref:`build-customization:where to put files` with custom build commands to generate offline formats for any documentation framework.

   With :doc:`builds from pull requests </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.

.. code-block:: yaml

   version: 2

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

python.install
``````````````

Read the Docs uses :doc:`pip <pip:index>` by default to install your Python packages.
It also supports `uv <https://docs.astral.sh/uv/>`__ through ``python.install``.
If you are using a :ref:`Conda <config-file/v2:conda>` environment to manage your build,
you'll need to use the Conda ``environment`` file instead.
If you have a commercial plan you can also install :doc:`private dependencies </guides/private-python-packages>`.

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

.. note::

   When using ``method: uv``, currently only one entry is allowed under ``python.install``.

: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:

.. code-block:: yaml

   version: 2

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

Packages
''''''''

Install the project using ``pip install``.
The use of ``python setup.py install`` is 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), ``uv``
:Default: ``pip``

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

.. _Extra Requirements: https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#optional-dependencies
.. _package dependencies: https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#declaring-required-dependency

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

For example, to run ``pip install .[docs]``:

.. code-block:: yaml

   version: 2

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

uv
''

Install dependencies using `uv <https://docs.astral.sh/uv/>`__.

Set ``method: uv`` and choose one of the following commands:

- ``command: sync`` to run ``uv sync`` using your ``pyproject.toml`` and, if present, ``uv.lock``
- ``command: pip`` to run ``uv pip install`` from a requirements file or a local path

:Key: ``command``
:Options: ``sync``, ``pip``
:Required: ``true``

Use ``path`` to point uv at a project that is not located at the repository root.

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

With ``command: sync``, you can select dependency groups from ``pyproject.toml``.
Use either a list of group names or ``all``.

:Key: ``groups``
:Type: ``list`` or ``all``
:Required: ``false``

With either uv command, you can install optional dependencies.
Use either a list of extras or ``all``.

:Key: ``extras``
:Type: ``list`` or ``all``
:Required: ``false``

With ``command: pip``, you can install from a requirements file.

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

.. note::

    ``command: sync`` doesn't allow ``requirements``.
    ``command: pip`` requires either ``requirements`` or ``path``.
    ``groups`` is only supported with ``command: sync``.

For example, to run ``uv sync --group docs``:

.. code-block:: yaml

    version: 2

    python:
       install:
          - method: uv
            command: sync
            groups:
               - docs

For example, to run ``uv pip install -r docs/requirements.txt``:

.. code-block:: yaml

    version: 2

    python:
       install:
          - method: uv
            command: pip
            requirements: docs/requirements.txt

For example, to run ``uv pip install .[docs]``:

.. code-block:: yaml

    version: 2

    python:
       install:
          - method: uv
            command: pip
            path: .
            extras:
               - docs

conda
~~~~~

Configuration for Conda support.

.. code-block:: yaml

   version: 2

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

   conda:
     environment: environment.yml

conda.environment
`````````````````

The path to the Conda `environment file <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_, 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.

.. code-block:: yaml

   version: 2

   build:
     os: ubuntu-24.04
     tools:
       python: "3.13"
       nodejs: "22"
       rust: "1.82"
       golang: "1.23"

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`` (deprecated), ``ubuntu-22.04``, ``ubuntu-24.04``, ``ubuntu-26.04``, ``ubuntu-lts-latest``
:Required: ``true``

.. note::

   The ``ubuntu-lts-latest`` option refers to the latest Ubuntu LTS version of Ubuntu available on Read the Docs,
   which may not match the latest Ubuntu LTS officially released.

.. warning::

   Using ``ubuntu-lts-latest`` may break your builds unexpectedly if your project isn't compatible with the newest Ubuntu LTS version when it's updated by Read the Docs.

build.tools
```````````

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

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

.. note::

   Each tool has a ``latest`` option available, which refers to the latest version available on Read the Docs,
   which may not match the latest version officially released.
   Versions and the ``latest`` option are updated at least once every six months to keep up with the latest releases.

.. warning::

   Using ``latest`` may break your builds unexpectedly if your project isn't compatible with the newest version of the tool when it's updated by Read the Docs.

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 :doc:`/guides/conda` guide
   for more information.

:Type: ``string``
:Options:
  - ``2.7``
  - ``3`` (alias for the latest 3.x version available on Read the Docs)
  - ``3.6``
  - ``3.7``
  - ``3.8``
  - ``3.9``
  - ``3.10``
  - ``3.11``
  - ``3.12``
  - ``3.13``
  - ``3.14``
  - ``latest`` (alias for the latest version available on Read the Docs)
  - ``miniconda3-4.7``
  - ``miniconda3-3.12-24.1``
  - ``miniconda3-3.12-24.9``
  - ``miniconda-latest`` (alias for the latest version available on Read the Docs)
  - ``mambaforge-4.10`` (deprecated)
  - ``mambaforge-22.9`` (deprecated)
  - ``mambaforge-23.11`` (deprecated)
  - ``mambaforge-latest`` (deprecated - alias for the latest version available on Read the Docs)
  - ``miniforge3-25.11``
  - ``miniforge3-latest`` (alias for the latest version available on Read the Docs)

build.tools.nodejs
``````````````````

Node.js version to use.

:Type: ``string``
:Options:
   - ``14``
   - ``16``
   - ``18``
   - ``19``
   - ``20``
   - ``22``
   - ``23``
   - ``24``
   - ``latest`` (alias for the latest version available on Read the Docs)

build.tools.ruby
````````````````

Ruby version to use.

:Type: ``string``
:Options:
   - ``3.3``
   - ``3.4``
   - ``latest`` (alias for the latest version available on Read the Docs)

build.tools.rust
````````````````

Rust version to use.

:Type: ``string``
:Options:
   - ``1.55``
   - ``1.61``
   - ``1.64``
   - ``1.70``
   - ``1.75``
   - ``1.78``
   - ``1.82``
   - ``1.86``
   - ``1.91``
   - ``latest`` (alias for the latest version available on Read the Docs)

build.tools.golang
``````````````````

Go version to use.

:Type: ``string``
:Options:
   - ``1.17``
   - ``1.18``
   - ``1.19``
   - ``1.20``
   - ``1.21``
   - ``1.22``
   - ``1.23``
   - ``1.24``
   - ``1.25``
   - ``latest`` (alias for the latest version available on Read the Docs)

build.apt_packages
``````````````````

List of `APT packages`_ to install.
Our build servers run various Ubuntu LTS versions with the default set of package repositories installed.
We don't currently support PPA's or other custom repositories.

.. _APT packages: https://packages.ubuntu.com/

:Type: ``list``
:Default: ``[]``

.. code-block:: yaml

   version: 2

   build:
     apt_packages:
       - libclang
       - cmake

.. note::

   When possible avoid installing Python packages using apt (``python3-numpy`` for example),
   :doc:`use pip or conda instead </guides/reproducible-builds>`.

.. warning::

   Currently, it's not possible to use this option when using :ref:`config-file/v2:build.commands`.


build.jobs
``````````

Commands to be run before or after a Read the Docs :term:`pre-defined build jobs`, or to override a specific job.
This allows you to run custom commands at a particular moment in the build process.
See :doc:`/build-customization` for more details.


.. code-block:: yaml

   version: 2

   build:
     os: ubuntu-24.04
     tools:
       python: "3.13"
     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 build step consists of a list of commands to be executed.
   ``build.os`` and ``build.tools`` are also required to use ``build.jobs``.

.. note::

   If the :ref:`config-file/v2:sphinx` or  :ref:`config-file/v2:mkdocs` keys are present in the configuration file,
   the default steps for each tool will be executed for the ``create_environment``, ``install``, and ``build`` steps.
   You can override any of these steps, but be aware that some steps may depend on others,
   for example, the default ``install`` and ``build`` steps depend on the ``create_environment`` step creating the Python virtual environment in a specific directory.

   If neither of the ``sphinx`` or ``mkdocs`` keys are present in the configuration file,
   only the specified ``build.tools`` and ``build.apt_packages`` will be installed,
   you will in charge of generating the documentation in the :ref:`$READTHEDOCS_OUTPUT <build-customization:where to put files>` directory.

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

build.jobs.build
````````````````

Commands to override the default build process.
When running builds from pull requests, only the ``html`` step will be executed.

.. code-block:: yaml

   version: 2

   formats: [pdf, epub]
   build:
     os: ubuntu-24.04
     tools:
       python: "3.13"
     jobs:
       create_environment:
         - echo "Preparing environment"
       install:
         - echo "Installing dependencies"
       build:
         html:
           - echo "Building HTML"
           - mkdir -p $READTHEDOCS_OUTPUT/html/
           - echo "Hello world!" > $READTHEDOCS_OUTPUT/html/index.html
         pdf:
           - echo "Building PDF"
           - mkdir -p $READTHEDOCS_OUTPUT/pdf/
           - echo "Hello world!" > $READTHEDOCS_OUTPUT/pdf/index.pdf
         epub:
           - echo "Building ePub"
           - mkdir -p $READTHEDOCS_OUTPUT/epub/
           - echo "Hello world!" > $READTHEDOCS_OUTPUT/epub/index.epub

:Type: ``dict``
:Allowed keys: ``html``, ``pdf``, ``epub``, ``htmlzip``
:Required: ``false``
:Default: ``{}``

.. note::

   If any of the ``pdf``, ``epub``, or ``htmlzip`` steps are overridden,
   they should be included in the :ref:`config-file/v2:formats` list.

.. note::

   For each format, you need to generate their output in the :ref:`$READTHEDOCS_OUTPUT <build-customization:where to put files>` directory.

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 :term:`pre-defined build jobs` will be executed.

.. code-block:: yaml

   version: 2

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

But we recommend using :ref:`config-file/v2:build.jobs` instead:

.. code-block:: yaml
   :caption: .readthedocs.yaml

   version: 2
   build:
     os: "ubuntu-22.04"
     tools:
       python: "3.10"
     jobs:
       install:
         - pip install pelican
       build:
         html:
           - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

``build.jobs`` offers the same functionality as ``build.commands``,
but in a more structured way that allows you to define different commands for each format,
while also supporting installing system dependencies via ``build.apt_packages``.
See :doc:`/build-customization` for more details.

.. note::

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

.. note::

   All items in the ``build.commands`` array are executed in a clean shell environment, i.e. environment changes do not
   persist and the working directory always start from the git repo.

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


sphinx
~~~~~~

Configuration for Sphinx documentation.

.. code-block:: yaml

   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 :ref:`config-file/v2:requirements file` and  :ref:`config-file/v2: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 :ref:`config-file/v2:packages`).
   This also allows you to override :ref:`the default pinning done by Read the Docs
   if your project was created before October 2020 <build-default-versions:external dependencies>`.

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``
:Required: ``true``

sphinx.fail_on_warning
``````````````````````

Turn warnings into errors
(:option:`-W <sphinx:sphinx-build.-W>` and :option:`--keep-going <sphinx:sphinx-build.--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.

.. code-block:: yaml

   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 :ref:`config-file/v2:requirements file` and  :ref:`config-file/v2: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 :ref:`config-file/v2:packages`).
   This also allows you to override :ref:`the default pinning done by Read the Docs
   if your project was created before March 2021 <build-default-versions:external dependencies>`.

mkdocs.configuration
````````````````````

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

:Type: ``path``
:Required: ``true``

mkdocs.fail_on_warning
``````````````````````

`Turn warnings into errors <https://www.mkdocs.org/user-guide/configuration/#strict>`__.
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.

.. code-block:: yaml

   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.

   .. code-block:: yaml

      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: []``.

   .. code-block:: yaml

      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 :doc:`/server-side-search/index`.

.. code-block:: yaml

   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 relative paths of the HTML files produced by the build,
you should try to match ``index.html``, not ``docs/index.rst``, nor ``/en/latest/index.html``.
Patterns can include one or more of the following special characters:

- ``*`` matches everything, including slashes.
- ``?`` 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 :ref:`config-file/v2:search.ignore`.

.. code-block:: yaml

   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 named guides.html,
       # two patterns are needed to match both the root and nested files.
       'guides.html': 3
       '*/guides.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 paths of the HTML files produced by the build,
you should try to match ``index.html``, not ``docs/index.rst``, nor ``/en/latest/index.html``.
Patterns can include one or more of the following special characters:

- ``*`` matches everything (including slashes).
- ``?`` matches any single character.
- ``[seq]`` matches any character in ``seq``.

.. code-block:: yaml

   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,
        # two patterns are needed to match both the root and nested files.
        - 'ref.html'
        - '*/ref.html'

.. code-block:: yaml

   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 <https://github.com/readthedocs/readthedocs.org/blob/main/readthedocs/rtd_tests/fixtures/spec/v2/schema.json>`_.
This schema is available at `Schema Store`_, use it with your favorite editor for validation and autocompletion.

.. _Schema Store: https://www.schemastore.org/