Installing Sphinx — Sphinx documentation

Sphinx is a Python application. It can be installed in one of the ways described below.
Installation methods
OS-specific package manager
Installation of the latest development release
Installation from source
After installation, you can check that Sphinx is available by running
This should print out the Sphinx version number.
For local development, it is generally recommended to install Sphinx into a non-global environment (using for example venv or conda environments). This will allow for the use of separate sphinx versions and third-party extensions for each sphinx project.
Sphinx packages are published on the Python Package Index (PyPI). The preferred tool for installing packages from PyPI is pip, which is included in all modern versions of Python.
Run the following command:
To avoid issues when rebuilding your environment, it is advisable to pin sphinx and third-party extension versions in a requirements.txt file:
Or, if writing documentation for a Python package, place the dependencies in the pyproject.toml file:
To work with conda, you need a conda-based Python distribution such as anaconda, miniconda, miniforge or micromamba.
Sphinx is available both via the anaconda main channel (maintained by Anaconda Inc.)
as well as via the conda-forge community channel
You may install a global version of Sphinx into your system using OS-specific package managers. However, be aware that this is less flexible and you may run into compatibility issues if you want to work across different projects.
Install either python3-sphinx using apt-get:
If it not already present, this will install Python for you.
Install python-sphinx using yum:
If it not already present, this will install Python for you.
Most Linux distributions have Sphinx in their package repositories. Usually the package is called python3-sphinx, python-sphinx or sphinx. Be aware that there are at least two other packages with sphinx in their name: a speech recognition toolkit (CMU Sphinx) and a full-text search database (Sphinx search).
Sphinx can be installed using Homebrew, MacPorts.
For more information, refer to the package overview.
Install either python3x-sphinx using port:
To set up the executable paths, use the port select command:
For more information, refer to the package overview.
Sphinx can be installed using Chocolatey.
You would need to install Chocolatey before running this.
For more information, refer to the chocolatey page.
Docker images for Sphinx are published on the Docker Hub. There are two kind of images:
sphinxdoc/sphinx-latexpdf
Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX. Please choose one for your purpose.
sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large (over 2GB!).
When using docker images, please use docker run command to invoke sphinx commands. For example, you can use following command to create a Sphinx project:
And you can use the following command to build HTML document:
For more details, please read README file of docker images.
You can install the latest development from PyPI using the --pre flag:
You will not generally need (or want) to do this, but it can be useful if you see a possible bug in the latest stable release.
You can install Sphinx directly from a clone of the Git repository. This can be done either by cloning the repo and installing from the local clone, on simply installing directly via git.
You can also download a snapshot of the Git repo in either tar.gz or zip format. Once downloaded and extracted, these can be installed with pip as above.