{"id":9320,"library":"sphinx-jupyterbook-latex","title":"Sphinx Jupyter Book LaTeX","description":"Sphinx Jupyter Book LaTeX is a Sphinx extension designed to enhance LaTeX build capabilities for Jupyter Book projects. It provides a set of transforms and post-transforms that configure Sphinx to correctly handle Jupyter Book's `_toc.yml` structure and produce PDF output that closely mirrors the HTML version. Version 1.0.0 is current, and releases generally align with updates in the broader Jupyter Book ecosystem.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-jupyterbook-latex","tags":["sphinx","jupyter-book","latex","documentation","publishing","pdf","executablebooks"],"install":[{"cmd":"pip install sphinx-jupyterbook-latex","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core documentation generation engine that this library extends. Explicitly requires >=3.9 in PyPI metadata.","package":"Sphinx","optional":false},{"reason":"This extension is specifically built to support LaTeX output for Jupyter Book projects and is often included by default in them.","package":"jupyter-book","optional":true},{"reason":"Required system dependency for 'sphinx.ext.imgconverter' (which this extension uses) to convert images like PNG/GIF for LaTeX/PDF output.","package":"ImageMagick","optional":false}],"imports":[{"note":"This library is a Sphinx extension and is enabled by adding its name to the 'extensions' list in Sphinx's conf.py. Direct Python imports are rarely needed by end-users.","symbol":"sphinx_jupyterbook_latex","correct":"extensions = ['sphinx_jupyterbook_latex'] # in conf.py"}],"quickstart":{"code":"# 1. Install the library\npip install sphinx-jupyterbook-latex\n\n# 2. Add it to your Sphinx conf.py\n# If you're using Jupyter Book, this extension is often enabled by default.\n# For a standalone Sphinx project, add:\nextensions = [\n    'sphinx_jupyterbook_latex',\n    # other extensions like 'myst_parser', 'jupyter_book_theme', etc.\n]\n\n# 3. Ensure ImageMagick is installed on your system for image conversion\n# Example for Debian/Ubuntu:\n# sudo apt-get install imagemagick\n\n# 4. Build your book to PDF (example using jupyter-book CLI)\n# jupyter-book build --builder latex your_book_folder\n# For Sphinx, use: make latexpdf","lang":"bash","description":"To get started, install the package via pip. Then, enable the Sphinx extension by adding 'sphinx_jupyterbook_latex' to your `extensions` list in `conf.py`. Note that ImageMagick is a required system dependency for image processing. If building with Jupyter Book, it often handles much of this configuration automatically."},"warnings":[{"fix":"Install `ImageMagick` on your operating system. For Debian-based systems, use `sudo apt-get install imagemagick`.","message":"For proper image conversion (e.g., PNG/GIF to PDF-compatible formats), `sphinx-jupyterbook-latex` utilizes `sphinx.ext.imgconverter`, which in turn requires the system-level tool `ImageMagick` to be installed. Without it, image rendering in PDF output may fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade `sphinx-jupyterbook-latex` to version `1.0.0` or newer to ensure compatibility with Sphinx 5 and higher: `pip install --upgrade sphinx-jupyterbook-latex`.","message":"Older versions of `sphinx-jupyterbook-latex` (e.g., `0.4.6`) had an upper bound requirement of `sphinx<5`, causing incompatibility issues with Sphinx 5.x.x.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Avoid nesting headings within content blocks. Use bold text or a custom directive if you need to highlight text within such blocks instead of a full heading.","message":"Embedding headings (e.g., `## My Heading`) inside admonitions or other content blocks in MyST Markdown can lead to unpredictable breakage of the document structure in Sphinx/Jupyter Book PDF output.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of potential formatting differences. If `individualpages` output is critical, consider building the full book PDF and then splitting it, or manually adjusting LaTeX templates (advanced). The ExecutableBooks project is actively working on improving this.","message":"The `--individualpages` LaTeX builder option in Jupyter Book does not fully leverage the improvements introduced by `sphinx-jupyterbook-latex` and uses the default Sphinx LaTeX writer. This may result in inconsistent output compared to the main 'book' PDF.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install ImageMagick on your system. For Debian/Ubuntu, use `sudo apt-get install imagemagick`. For other OS, refer to ImageMagick's official installation guide.","cause":"The `sphinx.ext.imgconverter` extension, used by `sphinx-jupyterbook-latex` for image conversion, relies on the external `ImageMagick` tool which is not installed or not found in the system's PATH.","error":"LaTeX Error: File `some_image.png` not found. Or similar image conversion failures during PDF build."},{"fix":"Add the following to your `latex_elements['preamble']` in `conf.py`: `r'\\usepackage{etoolbox}\\robustify\\( \\robustify\\)'`.","cause":"Sphinx's default handling of math environments (using parentheses) can conflict when included in LaTeX's table of contents. This was a common issue in older Sphinx versions.","error":"LaTeX Error: Bad math environment delimiter. (Often seen with math in section titles)"},{"fix":"In `conf.py`, modify `latex_elements` to include `'classoptions': ',openany'` to allow chapters to start on any page. To ensure page numbers, add `\\pagestyle{plain}` to your `latex_elements['preamble']`.","cause":"Sphinx's default LaTeX `manual` document class often forces new chapters/sections onto right-hand pages. Other issues can arise from page styling.","error":"PDF output contains many blank pages or incorrect page numbering/layout."},{"fix":"Upgrade `sphinx-jupyterbook-latex` to its latest version (1.0.0 or higher) which includes compatibility for Sphinx 5+: `pip install --upgrade sphinx-jupyterbook-latex`.","cause":"An older version of `sphinx-jupyterbook-latex` (e.g., 0.4.6) was installed, which had an explicit upper version constraint on Sphinx, making it incompatible with Sphinx 5.x.x.","error":"ERROR: 'sphinx-jupyterbook-latex' requires 'sphinx<5,>=3' but you have 'sphinx 5.0.1' which is incompatible."}]}