{"id":7331,"library":"jupyter-book","title":"Jupyter Book","description":"Jupyter Book is an open-source tool for building publication-quality books and documents from computational material. It enables users to write content using Markdown or Jupyter notebooks, embed computational elements, and generate interactive web-based books and publication-quality PDFs. Currently at version 2.1.4, it is an actively developed sub-project of Project Jupyter, with its evolution guided by the Executable Books Project community.","status":"active","version":"2.1.4","language":"en","source_language":"en","source_url":"https://github.com/jupyter-book/jupyter-book","tags":["documentation","publishing","jupyter","sphinx","markdown","books","computational narratives","static site generator","myst"],"install":[{"cmd":"pip install jupyter-book","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Recommended for publishing books to GitHub Pages.","package":"ghp-import","optional":true},{"reason":"Core dependency for parsing and executing Jupyter Notebooks within MyST Markdown. Directly integrated and updated by jupyter-book.","package":"myst-nb","optional":false},{"reason":"Core dependency for parsing MyST Markdown. Directly integrated and updated by jupyter-book.","package":"myst-parser","optional":false}],"imports":[],"quickstart":{"code":"# 1. Install Jupyter Book\npip install jupyter-book\n\n# 2. Clone a sample project (e.g., mystmd-quickstart)\ngit clone https://github.com/jupyter-book/mystmd-quickstart.git\ncd mystmd-quickstart\n\n# 3. Initialize a Jupyter Book project (creates myst.yml)\njupyter book init .\n\n# 4. (Optional) Install dependencies for notebook execution\npip install -r requirements.txt\n\n# 5. Build your book\njupyter book build . --execute\n\n# 6. Serve your book locally\njupyter book start","lang":"bash","description":"This quickstart guides you through setting up a new Jupyter Book project, cloning an example, building it, and serving it locally. The `--execute` flag ensures notebooks are run during the build process."},"warnings":[{"fix":"Review the official 'Upgrading to Jupyter Book 2' guide. Key changes include web page path conventions (underscores to hyphens), configuration file format (v1: `_config.yml`, v2: `myst.yml`), and some features still being reimplemented or having different behavior.","message":"Jupyter Book v2 is a complete rewrite of v1, built on the MyST Document Engine instead of Sphinx. This introduced significant breaking changes.","severity":"breaking","affected_versions":"All versions >= 2.0.0 (when migrating from < 2.0.0)"},{"fix":"Commonly, `jupyter_execute_notebooks` has been deprecated in favor of `nb_execution_mode`. Refer to the `myst-nb` and `myst-parser` documentation for a complete list of updated configuration options. Warnings are usually issued during build with the new name.","message":"Updates in `jupyter-book>=0.14` (which incorporates `myst-nb` and `myst-parser` updates) introduced breaking changes, particularly in configuration option names for notebook execution.","severity":"breaking","affected_versions":">= 0.14.0"},{"fix":"This is a minor visual artifact due to client-side rendering. There is no direct fix, but optimizing page load times can reduce its visibility.","message":"When using cell tags to hide inputs or outputs, the content may briefly appear before the JavaScript fully loads and hides it.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Interact with Jupyter Book via its CLI commands (`jupyter book init`, `jupyter book build`, `jupyter book start`) rather than attempting to `import jupyter_book` in Python scripts for core functionality.","message":"Jupyter Book is primarily a command-line interface (CLI) tool. It is not typically imported as a Python library for programmatic use in user code, but rather orchestrates other Python packages like Sphinx, MyST-NB, and MyST-Parser.","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":"Ensure `pip install jupyter-book` completed successfully. Verify your Python environment's script directory is in your system's PATH. If using a virtual environment, ensure it's activated. Reinstalling Python/Anaconda with default settings can often fix PATH issues.","cause":"The `jupyter-book` executable is not in your system's PATH, or Jupyter Book was not installed correctly.","error":"jupyter: command not found"},{"fix":"Update your configuration file(s). Replace `jupyter_execute_notebooks` with `nb_execution_mode`. Check other deprecated options in the `myst-nb` documentation.","cause":"You are using an old configuration option name in your `myst.yml` or `_config.yml` file.","error":"WARNING: 'jupyter_execute_notebooks' is deprecated for 'nb_execution_mode' [mystnb.config]"},{"fix":"Consult the MyST Cheat Sheet and MyST Guide for correct syntax, especially for directives, cross-references, and admonitions. Ensure custom Sphinx extensions are correctly configured for MyST.","cause":"The MyST syntax (especially for directives and roles) can be particular and differs from standard Markdown or reStructuredText/Sphinx.","error":"Syntax errors related to MyST/Sphinx directives, e.g., 'Unknown directive type 'my-directive'.'"},{"fix":"Install a full LaTeX distribution (e.g., TeX Live, MiKTeX) on your system. Ensure the `pdflatex` executable is accessible from your system's PATH. This is especially common on Windows if a LaTeX distribution is not fully set up.","cause":"When building a PDF with the `pdflatex` builder, the `pdflatex` command (part of a LaTeX distribution) is not found in your system's PATH.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'pdflatex'"}]}