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:


Whether the build is running inside Read the Docs.




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.


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


The type of the version being built.


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


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


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


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.


    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


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:

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(
    auth=(username, password),

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

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