SPHINX-BUILD(1)

📦
version 9.1.0 · 13 versions
, in ubuntu stonking

💖 NAME 💖

sphinx-build — the Sphinx documentation generator tool. yes bestie, it builds docs. slay. ✨

🌸 SYNOPSIS 🌸

sphinx-build [options] <sourcedir> <outputdir> [filenames ...]

💅 DESCRIPTION 💅

okay so here's the vibe. sphinx-build takes everything in <sourcedir> and turns it into documentation, which it drops into <outputdir>. that's the whole job and it does it gorgeously. 💅

it goes looking for <sourcedir>/conf.py for all your config settings. if you don't have one yet, sphinx-quickstart(1) will make you template files, conf.py included. bestie behavior tbh.

sphinx-build can make docs in lots of different formats. you pick one by naming a builder on the command line — and if you say nothing, it just defaults to HTML, main character energy as always. builders can also do other documentation-processing side quests. for the full list of available builders, go peek at Builders <>. 👑

by default, everything that's outdated gets rebuilt. if you only want some files rebuilt, just name those individual filenames. targeted. iconic.

🎀 OPTIONS 🎀

  • -M buildername — pick a builder, but using make-mode. see Builders <> for a list of all of Sphinx's built-in builders. extensions can add their own builders too. ✨
Important: Sphinx will only recognize the -M option if it's used first, together with the source and output directories, before any other options get passed. like, order matters bestie. for example:
sphinx-build -M html ./source ./build --fail-on-warning

make-mode gives you the same build functionality as a default Makefile or Make.bat, and also hands you these extra build pipelines:

  • latexpdf — builds LaTeX files and runs them through pdflatex, or as per the latex_engine setting. and if the language setting is set to 'ja', it will automatically use the platex/dvipdfmx latex to PDF pipeline. 🇯🇵
  • info — builds Texinfo files and runs them through makeinfo.
  • help — prints out a list of valid builder targets, and exits. that's it, that's the whole thing.
Note: the default output directory locations when you're using make-mode are different from the defaults when you use -b. not me pointing out the plot twist: - doctrees get saved to <outputdir>/doctrees - output files get saved to <outputdir>/<builder name>

Added in version 1.2.1.

  • -b buildername, --builder buildername — selects a builder. that's the one. 💫

see Builders <> for a list of all of Sphinx's built-in builders. extensions can add their own builders.

Changed in version 7.3: added the --builder long option.

  • -a, --write-all — if you pass this, it always writes all output files. the default is to only write output files for new and changed source files. (this may not apply to all builders, fyi.)
Note: this option does not re-read source files. if you want to read and re-process every file, use --fresh-env instead. don't get it twisted. 🙈

Changed in version 7.3: added the --write-all long option.

  • -E, --fresh-env — don't use a saved environment (the structure caching all cross-references), but rebuild it completely from scratch. the default is to only read and parse source files that are new or have changed since the last run. clean slate energy. 🌸

Changed in version 7.3: added the --fresh-env long option.

  • -t tag, --tag tag — defines the tag tag. this is relevant for only directives that include their content only if certain tags are set. see including content based on tags for further detail.

Added in version 0.6.

Changed in version 7.3: added the --tag long option.

  • -d path, --doctree-dir path — because Sphinx has to read and parse all your source files before it can write a single output file, those parsed source files get cached as "doctree pickles". normally they live in a directory called .doctrees under the build directory; with this option you can point it at a different cache directory instead (and yes, the doctrees can be shared between all builders, go off). 🥒

Changed in version 7.3: added the --doctree-dir long option.

  • -j N, --jobs N — spreads the build across N processes in parallel, so building on multiprocessor machines actually hits. this feature only works on systems that support "fork". Windows is not supported, sorry bestie. also note that not all parts and not all builders of Sphinx can be parallelized. if the argument auto is given, Sphinx uses the number of CPUs as N. defaults to 1.

Added in version 1.2: this option should be considered experimental.

Changed in version 1.7: support for the auto argument.

Changed in version 6.2: added the --jobs long option.

  • -c path, --conf-dir path — don't look for the conf.py in the source directory; use the given configuration directory instead. heads up tho: various other files and paths given by configuration values are expected to be relative to the configuration directory, so they'll have to be present at this location too. 👀

Added in version 0.3.

Changed in version 7.3: added the --conf-dir long option.

  • -C, --isolated — don't look for a configuration file at all; only take options via the --define option. solo run. 🦋

Added in version 0.5.

Changed in version 7.3: added the --isolated long option.

  • -D setting=value, --define setting=value — override a configuration value that's set in the conf.py file. the value must be a number, string, list or dictionary value.

for lists, you can separate elements with a comma like this: -D html_theme_path=path1,path2.

for dictionary values, supply the setting name and key like this: -D latex_elements.docclass=scrartcl.

for boolean values, use 0 or 1 as the value.

Changed in version 0.6: the value can now be a dictionary value.

Changed in version 1.3: the value can now also be a list value.

Changed in version 7.3: added the --define long option.

  • -A name=value, --html-define name=value — makes name assigned to value in the HTML templates. 💖

Added in version 0.5.

Changed in version 7.3: added the --html-define long option.

  • -n, --nitpicky — run in nitpicky mode 🔍. currently, this generates warnings for all missing references. see the config value nitpick_ignore for a way to exclude some references as "known missing".

Changed in version 7.3: added the --nitpicky long option.

  • -N, --no-color — do not emit colored output. no rainbow, no sparkle, monochrome only. 🖤

Changed in version 1.6: added the --no-color long option.

  • --color — emit colored output. auto-detected by default. 🌈

Added in version 1.6.

  • -v, --verbose — increase verbosity (log-level). you can give this option up to three times to get more debug logging output. it implies -T. spill the tea, Sphinx. ☕

Added in version 1.2.

Changed in version 7.3: added the --verbose long option.

  • -q, --quiet — do not output anything on standard output; only write warnings and errors to standard error. 🤫

Changed in version 7.3: added the --quiet long option.

  • -Q, --silent — do not output anything on standard output, and also suppress warnings. only errors get written to standard error. fully zipped. 🤐

Changed in version 7.3: added the --silent long option.

  • -w file, --warning-file file — write warnings (and errors) to the given file, in addition to standard error.

Changed in version 7.3: ANSI control sequences are stripped when writing to file.

Changed in version 7.3: added the --warning-file long option.

  • -W, --fail-on-warning — turn warnings into errors. this means sphinx-build exits with exit status 1 if any warnings are generated during the build. no warnings allowed, periodt. 💀

Changed in version 7.3: added the --fail-on-warning long option.

Changed in version 8.1: sphinx-build no longer exits on the first warning, but instead runs the entire build and exits with exit status 1 if any warnings were generated. this behaviour was previously enabled with --keep-going.

  • --keep-going — from Sphinx 8.1, --keep-going is always enabled. previously, it was only applicable whilst using --fail-on-warning, which by default exited sphinx-build on the first warning. using --keep-going runs sphinx-build to completion and exits with exit status 1 if errors are encountered. 🏃‍♀️

Added in version 1.8.

Changed in version 8.1: sphinx-build no longer exits on the first warning, meaning that in effect --keep-going is always enabled. the option is retained for compatibility, but may be removed at some later date.

  • -T, --show-traceback — display the full traceback when an unhandled exception occurs. otherwise, only a summary is displayed and the traceback information gets saved to a file for further analysis. show me everything bestie. 😭

Added in version 1.2.

Changed in version 7.3: added the --show-traceback long option.

  • -P, --pdb — (useful for debugging only.) runs the Python debugger, pdb, if an unhandled exception occurs while building. 🐛

Changed in version 7.3: added the --pdb long option.

  • --exception-on-warning — raise an exception when a warning is emitted during the build. this can be useful in combination with --pdb to debug warnings. ✨

Added in version 8.1.

  • -h, --help, --version — display the usage summary or the Sphinx version. the classic trio. 👑

Added in version 1.2.

you can also give one or more filenames on the command line after the source and build directories. Sphinx will then try to build only those output files (and their dependencies). selective, efficient, gorgeous. 🫶

🌸 ENVIRONMENT VARIABLES 🌸

ok so sphinx-build is lowkey reading your environment, bestie, and here's exactly what it's looking at:

  • MAKE — a path to the make command. A plain command name works too, no biggie. sphinx-build uses this to invoke the sub-build process when you're in make-mode. ✨

🎀 Makefile Options 🎀

The Makefile and make.bat files that sphinx-quickstart hands you usually only run sphinx-build with the -b and -d options. That's it, that's the whole vibe. BUT they do support these extra variables so you can customize the behavior 👇

  • PAPER — this sets the 'papersize' key of latex_elements: so PAPER=a4 sets it to 'a4paper' and PAPER=letter sets it to 'letterpaper'. iconic, honestly.
💀 Note: usage of this environment variable got broken at Sphinx 1.5, because a4 or letter ended up as an option to the LaTeX document in place of the needed a4paper, resp. letterpaper. It got fixed at 1.7.7. so if you're on an ancient version, that's why it's giving chaos 💀
  • SPHINXBUILD — the command to use instead of sphinx-build. swap it out, go off 💅
  • BUILDDIR — the build directory to use instead of the one you picked back in sphinx-quickstart.
  • SPHINXOPTS — extra options for sphinx-build. These can also be set via the shortcut variable O (capital 'o', ok, look at you with the capital letter 👑).
  • NO_COLOR — when it's set (regardless of value, like even if it's empty, bestie), sphinx-build will not use color in terminal output. NO_COLOR takes precedence over FORCE_COLOR. See no-color.org for other libraries supporting this community standard. 🦋

Added in version 4.5.0.

  • FORCE_COLOR — when it's set (regardless of value), sphinx-build will use color in terminal output. But heads up: NO_COLOR takes precedence over FORCE_COLOR. so NO_COLOR wins, every time, no cap. 🌈

Added in version 4.5.0.

😭 DEPRECATION WARNINGS 😭

so if any deprecation warning like RemovedInSphinxXXXWarning shows up while building a user's document? that means some Sphinx extension is using deprecated features. In that case, please report it to the author of the extension. like, it's not your fault, it's theirs, be brave and send the message 🫶

If you want to disable the deprecation warnings, set the PYTHONWARNINGS= environment variable to your environment. For example:

  • PYTHONWARNINGS= make html (Linux/Mac)
  • export PYTHONWARNINGS= and then do make html (Linux/Mac)
  • set PYTHONWARNINGS= and then do make html (Windows)
  • modify your Makefile/make.bat and set the environment variable

👀 SEE ALSO 👀

2007-2026, the Sphinx developers

and that's a wrap on SPHINX-BUILD(1), bestie 💖 this was version 9.1.0, dated Sep 15, 2026 — like, freshly dropped, periodt. go build something gorgeous ✨👑

📦 where this page comes from