# Configuration File V2¶

Read the Docs supports configuring your documentation builds with a YAML file. The configuration file must be in the root directory of your project and be named .readthedocs.yaml.

All options are applied to the version containing this file. Below is an example YAML file which shows the most common configuration options:

# .readthedocs.yaml
# Read the Docs configuration file

# Required
version: 2

# Set the version of Python and other tools you might need
build:
os: ubuntu-20.04
tools:
python: "3.9"
# You can also specify other tool versions:
# nodejs: "16"
# rust: "1.55"
# golang: "1.17"

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

# formats:
#    - pdf

# 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¶

Formats of the documentation to be built.

Type

list

Options

htmlzip, pdf, epub

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

pdf, epub, and htmlzip output is not supported when using MkDocs.

### python¶

Configuration of the Python environment to be used.

version: 2

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


#### python.version¶

Warning

This option is now deprecated and replaced by . See 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

true

Example:

version: 2

python:
version: "3.7"
install:
- requirements: docs/requirements.txt
- requirements: requirements.txt


Warning

If you are using a 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 python setup.py install or pip install.

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

Key

path

Type

path

Required

true

The installation method.

Key

method

Options

pip, setuptools

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:
version: "3.7"
install:
- method: pip
path: .
extra_requirements:
- docs
- method: setuptools
path: package


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


span.prompt1:before {
content: "\$ ";
}
pip install .[docs]
python package/setup.py install


#### python.system_packages¶

Type

bool

Default

false

Warning

If you are using a environment to manage the build, this setting will not have any effect, since the virtual environment creation is managed by Conda.

### conda¶

Configuration for Conda support.

version: 2

conda:
environment: environment.yml


#### conda.environment¶

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

Type

path

Required

true

### build (beta specification)¶

Warning

This functionality is in beta. If you find any inconsistencies or have feedback, please open an issue.

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-20.04
tools:
python: "3.9"
nodejs: "16"
rust: "1.55"
golang: "1.17"


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

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 interpretes and versions, from CPython, PyPy, Miniconda, and Mamba.

Note

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

Type

string

Options
• 2.7

• 3 (last stable CPython version)

• 3.6

• 3.7

• 3.8

• 3.9

• 3.10

• pypy3.7

• miniconda3-4.7

• mambaforge-4.10

#### build.tools.nodejs¶

Node.js version to use.

Type

string

Options

14, 16

#### build.tools.rust¶

Rust version to use.

Type

string

Options

1.55

#### build.tools.golang¶

Go version to use.

Type

string

Options

1.17

#### 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), .

### sphinx¶

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

version: 2

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


#### 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 ( and 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


#### 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.

## Schema¶

You can see the complete schema here.

## 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 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 speficiation, the build.os 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, pypy3.5

• latest: 2, 2.7, 3, 3.5, 3.6, 3.7, 3.8, pypy3.5

#### python.version (legacy)¶

The Python version (this depends on ).

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

• The default value of the 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 .

• The setting conda.file was renamed to conda.environment. See .

• The build.image setting has been replaced by build.os. See . 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 .

• The setting python.use_system_site_packages was renamed to python.system_packages. See .

• The build will fail if there are invalid keys (strict mode).

Warning

Some values from the web interface are no longer respected, please see 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 .

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