Upgrade an existing book from Jupyter Book 1

tl;dr to upgrade¶

• Create and activate a virtual environment with Jupyter Book 2.

• Run jupyter book inside your existing book directory to automatically upgrade to Jupyter Book 2 (typically a myst.yml file will be created).

• Some manual cleanup may be needed to address build warnings.

• Some functionality in your book may be missing in Jupyter Book 2 (see What are the known current limitations in Jupyter Book 2?).

Should You Upgrade?¶

Upgrade for:

• Faster builds

• Modern features and active development

• Better performance

Stay on 1.0 if you rely on:

• Custom Sphinx extensions you cannot port

• Key functionality not yet implemented (see What are the known current limitations in Jupyter Book 2?)

What You Need to Know¶

Jupyter Book 1 uses two configuration files:

• _config.yml - Book metadata and settings

• _toc.yml - Table of contents structure

Jupyter Book 2 uses one:

• myst.yml - All configuration in a single file

The upgrade process automatically converts these files for you.

Example: A typical Jupyter Book 1 project (https://github.com/jupyter-book/legacy-demo-book/):

_config.yml      # Book metadata and settings
_toc.yml         # Table of contents
intro.md
notebooks.ipynb
logo.png

How to Upgrade¶

Step 1: Install Jupyter Book 2¶

pip install jupyter-book
jupyter book --version  # Should show v2...

Step 2: Run the upgrade command¶

Navigate to your book directory and run:

cd my-book
jupyter book

The CLI will detect your Jupyter Book 1 project and prompt you to upgrade:

? 📘 Found a legacy Jupyter Book. To proceed, myst needs to perform an upgrade which will:
‣ Upgrade any Sphinx-style glossaries to MyST-style glossaries
‣ Upgrade any case-insensitive admonition names to lowercase (Note → note)
‣ Migrate configuration from _config.yml and (if applicable) _toc.yml files
‣ Rename any modified or unneeded files so that they are hidden

Are you willing to proceed? (Y/n)

Step 3: Accept the upgrade¶

Press Y to start the upgrade. The tool will:

• Create a new myst.yml file with your configuration

• Back up your original files as ._config.yml.myst.bak and ._toc.yml.myst.bak

• Update syntax where needed

💾 Writing new config file: myst.yml
Migrating Jupyter Book configuration to myst.yml
Migrating TOC to myst.yml

Step 4: Preview your book¶

When prompted, press Y to start the preview server:

? Would you like to run jupyter book start now? (Y/n)

This launches a local server where you can preview your upgraded book and verify everything works correctly.

Upgrade a Sphinx Site¶

To convert a Sphinx site to Jupyter Book, you need to replace {toctree} directives with a MyST Table of Contents.

Generate a starter TOC¶

cd book-folder
jupyter book init --write-toc

This creates a TOC based on your file structure.

Map your toctree structure¶

Re-order the generated TOC to match your {toctree} directives. For example:

Before (Sphinx):

```{toctree}
page1
page2
```

After (Jupyter Book):

toc:
- file: myfolder/index
  children:
  - file: myfolder/page1
  - file: myfolder/page2

Remove the {toctree} directives from your pages as you migrate them.

FAQ: Migration and Troubleshooting¶

See Migrating and troubleshooting upgrades.