Here is a step by step guide on how to install Read the Docs. It will get you to a point of having a local running instance.
Currently Read the Docs is using
Django 1.11.x and this version of Django
has a bug which breaks database migrations if you are using
sqlite 3.26.0 or Newer.
So, we recommend using
sqlite < 3.26.0 to run Read the Docs properly on your machine.
Additionally Read the Docs depends on:
Git (version >=2.17.0)
Mercurial (only if you need to work with mercurial repositories)
Pip (version >1.5)
Elasticsearch (only if you want full support for searching inside the site)
- Follow Search documentation for more instruction.
You can import Python 2.x or 3.x projects in RTD, make sure you install the appropriate Python version (2.x or 3.x) with virtualenv.
In order to get all the dependencies successfully installed, you need these libraries.
Get and run Read the Docs¶
Clone the repository somewhere on your disk and enter to the repository:
git clone --recurse-submodules https://github.com/readthedocs/readthedocs.org.git cd readthedocs.org
Create a virtual environment and activate it:
virtualenv --python=python3 venv source venv/bin/activate
Next, install the dependencies using
(make sure you are inside of the virtual environment):
pip install -r requirements.txt
This may take a while, so go grab a beverage. When it’s done, build the database:
python manage.py migrate
Then create a superuser account for Django:
python manage.py createsuperuser
Now let’s properly generate the static assets:
python manage.py collectstatic
Now you can optionally load a couple users and test projects:
python manage.py loaddata test_data
If you do not opt to install test data, you’ll need to create an account for
API use and set
SLUMBER_PASSWORD in order for
everything to work properly.
This can be done by using
createsuperuser, then attempting a manual login to
EmailAddress entry for the user, then you can use
update the object with
Finally, you’re ready to start the web server:
python manage.py runserver
For builds to properly work as expected,
it is necessary that the port you’re serving on
python manage.py runserver 0.0.0.0:8080)
matches the port defined in
You can use
readthedocs/settings/local_settings.py to modify this
(by default, it’s
While the web server is running,
you can build the documentation for the latest version of any project using the
For example to update the
python manage.py update_repos pip
If you have problems building a project successfully,
it is probably because of some missing libraries for
You can uncheck this on the advanced settings of your project.
After registering with the site (or creating yourself a superuser account), you will be able to log in and view the dashboard.
Importing your docs¶
One of the goals of readthedocs.org is to make it easy for any open source developer to get high quality hosted docs with great visibility! Simply provide us with the clone URL to your repo, we’ll pull your code, extract your docs, and build them!
We make available a post-commit webhook that can be configured to update the docs whenever you commit to your repo. See our Importing Your Documentation page to learn more.
By now you can trigger builds on your local environment, to encapsulate the build process inside a Docker container, see Build Environments.
For building this documentation, see Building and Contributing to Documentation.
And for setting up for the front end development, see Front End Development.