Environment Variables

Read the Docs supports two types of environment variables in project builds:

Both are merged together during the build process and are exposed to all of the executed commands. There are two exceptions for user-defined environment variables however:

  • User-defined variables are not available during the checkout step of the build process

  • User-defined variables that are not marked as public will not be available in pull request builds

Default environment variables

Read the Docs builders set the following environment variables automatically for each documentation build:

READTHEDOCS

Whether the build is running inside Read the Docs.

Default

True

READTHEDOCS_VERSION

The slug of the version being built, such as latest, stable, or a branch name like feature-1234. For pull request builds, the value will be the pull request number.

READTHEDOCS_VERSION_NAME

The verbose name of the version being built, such as latest, stable, or a branch name like feature/1234.

READTHEDOCS_VERSION_TYPE

The type of the version being built.

Values

branch, tag, external (for pull request builds), or unknown

READTHEDOCS_PROJECT

The slug of the project being built. For example, my-example-project.

READTHEDOCS_LANGUAGE

The locale name, or the identifier for the locale, for the project being built. This value comes from the project’s configured language.

Examples

en, it, de_AT, es, pt_BR

User-defined environment variables

If extra environment variables are needed in the build process (like an API token), you can define them from the project’s settings page:

  1. Go to your project’s Admin > Environment Variables

  2. Click on Add Environment Variable

  3. Fill the Name and Value

  4. Check the Public option if you want to expose this environment variable to builds from pull requests.

    Warning

    If you mark this option, any user that can create a pull request on your repository will be able to see the value of this environment variable.

  5. Click on Save

Note

Once you create an environment variable, you won’t be able to see its value anymore.

After adding an environment variable, you can read it from your build process, for example in your Sphinx’s configuration file:

conf.py
import os
import requests

# Access to our custom environment variables
username = os.environ.get('USERNAME')
password = os.environ.get('PASSWORD')

# Request a username/password protected URL
response = requests.get(
    'https://httpbin.org/basic-auth/username/password',
    auth=(username, password),
)

You can also use any of these variables from user-defined build jobs in your project’s configuration file:

.readthedocs.yaml
version: 2
build:
  os: ubuntu-22.04
  tools:
    python: 3.10
  jobs:
    post_install:
      - curl -u ${USERNAME}:${PASSWORD} https://httpbin.org/basic-auth/username/password