# Build process¶

Once a project has been imported and a build is triggered, Read the Docs executes specific pre-defined jobs to build the project’s documentation and update the hosted content. This page explains in detail what happens behind the scenes, and an overview of how you can change this process.

## Understanding what’s going on¶

Understanding how your content is built helps with debugging the problems that may appear in the process. It also allows you customize the steps of the build process.

Note

All the steps are run inside a Docker container with the image the project defines in .

The following are the pre-defined jobs executed by Read the Docs:

checkout

Checks out project’s code from the URL’s repository defined for this project. It will use git clone, hg clone, etc depending on the version control system you choose.

system_dependencies

Installs operating system & system-level dependencies. This includes specific version of languages (e.g. Python, Node.js, Go, Rust) and also apt packages.

At this point, can be used to define a language version, and to define apt packages.

create_environment

Creates a Python environment to install all the dependencies in an isolated and reproducible way. Depending on what’s defined by the project a virtualenv or a conda environment () will be used.

install

Install default common dependencies.

If the project has extra Python requirements, can be used to specify them.

Tip

We strongly recommend required to build the documentation to avoid unexpected build errors.

build

Runs the main command to build the documentation for each of the formats declared (). It will use Sphinx () or MkDocs () depending on the project.

Once the build process finishes successfully, the resulting artifacts are uploaded to our servers, and the CDN is purged so the newer version of the documentation is served.

If there are extra steps required to build the documentation, or you need to execute additional commands to integrate with other tools, it’s possible to run user-defined commands and customize the build process.

## Build resources¶

Every build has limited resources to avoid misuse of the platform. Currently, these build limits are:

• 15 minutes build time

• 3GB of memory

• 2 concurrent builds

We can increase build limits on a per-project basis. Send an email to support@readthedocs.org providing a good reason why your documentation needs more resources.

## Default environment variables¶

The Read the Docs builder sets the following environment variables when building your documentation:

Environment Variables

Environment variable

Description

Example value

READTHEDOCS

Whether the build is running inside RTD

True

READTHEDOCS_VERSION

The RTD slug of the version which is being built

latest

READTHEDOCS_VERSION_NAME

Corresponding version name as displayed in RTD’s version switch menu

stable

READTHEDOCS_VERSION_TYPE

Type of the event triggering the build

branch | tag | external (for pull request builds) | unknown

READTHEDOCS_PROJECT

The RTD slug of the project which is being built

my-example-project

READTHEDOCS_LANGUAGE

The RTD language slug of the project which is being built

en

Note

The term slug is used to refer to a unique string across projects/versions containing ASCII characters only. This value is used in the URLs of your documentation.

Tip

If extra environment variables are needed in the build process (like an API token), you can add them going to Admin > Environment Variables in your project. See Environment Variables.