Read the Docs custom domains: a DNS-first setup for verified HTTPS

Use a CNAME, then let Read the Docs verify it

The reliable way to serve a Read the Docs project from docs.example.com is to create a DNS CNAME record, add that hostname in the project’s custom-domain settings, wait for verification, and allow the HTTPS certificate to be issued. Do not substitute an A record or an IP address for the CNAME target.

This is a DNS-and-certificate workflow, not merely a redirect. The custom hostname must resolve to Read the Docs, Read the Docs must confirm that the project controls it, and certificate issuance must finish before visitors receive a clean HTTPS connection.

A worked configuration

Assume the project slug is example-project and the public hostname will be docs.example.com.

Setting	Example value
Project’s Read the Docs hostname	example-project.readthedocs.io
Public documentation hostname	docs.example.com
DNS record type	CNAME
DNS name	docs, or docs.example.com if the provider requires the full name
DNS target	example-project.readthedocs.io

Create the record in the DNS provider’s zone for example.com. You need permission to edit that zone. The provider may display the target with a trailing dot, such as example-project.readthedocs.io., which is equivalent.

Use the exact target shown by the project’s Custom Domains screen. If the screen specifies a different Read the Docs hostname, follow that value rather than guessing. A target containing https://, a path, or an IP address is not a valid CNAME value.

If the provider offers a proxy or “orange cloud” option, leave it disabled during the initial setup unless its documentation explicitly supports proxied custom domains for Read the Docs. Proxying can prevent the domain-verification or certificate checks from reaching the intended service.

Add and verify the domain in Read the Docs

1. Open the project’s administration settings and locate the Custom Domains section. The exact menu label can vary between dashboard versions.
2. Enter docs.example.com without a scheme, trailing slash, or port.
3. Save the hostname and wait for its status to become Verified, or the equivalent valid state shown by the dashboard.
4. Allow several minutes for the automatically provisioned Let’s Encrypt certificate to be issued after verification succeeds.

DNS changes often appear within an hour, but resolver caches and provider behavior can extend that time. If verification remains pending, compare the record’s name and target with the values shown in the project settings.

HTTP requests to a configured custom domain are redirected to HTTPS. A browser may show a certificate warning during the issuance window. That is a temporary provisioning state, not a reason to bypass the warning permanently or distribute the hostname before the certificate is valid.

Check the result from outside the dashboard

Run these commands from a workstation, administrator shell, or CI runner with DNS and outbound HTTPS access. They require no Read the Docs permissions. Replace the example hostname and project slug with your own values.

dig +short CNAME docs.example.com

The expected result is the project’s Read the Docs hostname, such as example-project.readthedocs.io. Some DNS resolvers flatten CNAME chains, so the absence of a CNAME line is not conclusive by itself. Check the resolved address and compare the result with the target configured in Read the Docs.

curl -I http://docs.example.com
curl -I https://docs.example.com

The HTTP request should redirect to the HTTPS URL. The HTTPS request should complete without a certificate error and return a successful response, normally a 2xx status or an intentional 3xx redirect. Do not use curl -k as the verification method; it hides the certificate problem you are trying to detect.

openssl s_client -connect docs.example.com:443 \
  -servername docs.example.com /dev/null |
  openssl x509 -noout -subject -issuer -ext subjectAltName

Look for docs.example.com in the subject or subject alternative name and for a Let’s Encrypt issuer in the certificate chain. Exact field formatting varies by OpenSSL version. A browser’s certificate-details panel is a useful cross-check.

Common failures and their causes

Symptom	Likely cause	Corrective action
Domain cannot be verified	Wrong CNAME target, an A record, proxying, or DNS not yet visible	Replace the record with the exact CNAME shown by Read the Docs, disable proxying initially, and allow propagation time.
The wrong project loads	The CNAME points to another project slug	Correct the target and retest both DNS resolution and the project content.
Browser shows a certificate warning	Verification or certificate issuance is still pending	Wait for the verified state and a valid certificate, then run the HTTPS checks again.
Removing the domain does not remove DNS	Project settings and DNS records are independent	Delete or deliberately repoint the DNS record after removing the custom domain.

Limits that affect the domain design

Read the Docs supports one custom domain per project. If several hostnames must serve distinct projects, use separate projects. If one hostname should merely redirect to another, plan an external redirect and check it for loops and for the canonical URL you want visitors and crawlers to see.

Use a subdomain for the standard CNAME workflow. A zone apex such as example.com generally cannot carry a normal CNAME record. Do not replace that requirement with an A record in this workflow; if an apex hostname is mandatory, confirm the current Read the Docs and DNS-provider requirements before changing production DNS.

Choose one canonical hostname for links, screenshots, and documentation references. Treat www and the apex as separate hostnames rather than assuming that adding one makes the other work.

Cutover and rollback

For a live site, lower the existing DNS TTL before the change if the provider permits it. Update internal links and service configurations to use the custom hostname only after the domain is verified and HTTPS succeeds.

If the change must be undone, remove the custom domain from the project settings first, then remove or repoint its CNAME record. Keep the normal example-project.readthedocs.io URL available as a fallback. Remember that cached DNS and previously issued certificates can make the transition appear incomplete for some visitors even after the configuration has been reverted.