Read the Docs local Docker Compose build parity with cloud .readthedocs.yaml

Answer the question first

When you run .readthedocs.yaml locally inside a Docker‑Compose stack, the only parts that are guaranteed identical to a cloud build are:

• The build_command and any commands sections – they run in the same container image.
• Environment variables defined under env – they are injected at container start.
• Any system_packages or apt_packages you list – they are installed inside the image the same way.
• Python packages installed via install_requires or a requirements.txt – pip resolves them from the same public indexes unless you override the index URL.

What can drift between environments are:

• The base image tag e.g. python:3.11-slim vs python:3.11-slim-bullseye determines the OS libraries and the default Python version.
• Network restrictions – cloud builds can reach PyPI and conda directly; local builds may hit a corporate proxy or be offline.
• Cache layers – the cloud uses a shared package cache; local builds use the host’s cache unless you clear it.

Steps to confirm parity

1. Pin the base image. In .readthedocs.yaml use a fully qualified tag, e.g. image: python:3.11.8-slim-bullseye. Then in your docker-compose.yml reference the exact same tag.
2. Pull the cloud worker image. The Read the Docs community cloud uses images like readthedocs/docs:2026-10-20. Run:

   docker pull readthedocs/docs:2026-10-20

   Then inspect:

   docker run --rm readthedocs/docs:2026-10-20 python --version
   docker run --rm readthedocs/docs:2026-10-20 pip list | head

   Compare the output with your local container.
3. Log the dependency install steps. In your docker-compose.yml add a step to capture the pip install log:

   services:
     worker:
       image: python:3.11.8-slim-bullseye
       command: bash -c "pip install -r requirements.txt > pip.log 2>&1"

   Then run docker-compose up worker and compare pip.log with the cloud build log.
4. Verify system packages. Inside the running container run:

   dpkg -l | grep <package>

   and compare with the system_packages section of your .readthedocs.yaml.
5. Check environment variables. In the container run env | grep <VAR> and confirm the values match the cloud build environment.

What to ask next

To narrow down any remaining discrepancy, could you provide the exact base image tag you use in your local docker-compose.yml?