install.md

title	Install Jupyter Book 2
subtitle	Install the Jupyter Book tools from PyPI, NPMJS, or conda-forge.
short_title	Install Jupyter Book

:::{seealso} Never used Jupyter Book before? :class: dropdown

Jupyter Book 2 is a very thin wrapper around the MyST-MD engine: it shares the same CLI and configuration file (see for more details). It serves primarily to as an introduction of the existing Jupyter Book community to the MyST-MD engine.

If you're new to the Jupyter Book project, consider directly using MyST-MD. :::

Jupyter Book is available on the PyPI, conda-forge, and npm package repositories as jupyter-book>=2. How you install Jupyter Book depends upon your choice of environment manager.

::::{hint} Should I use pip or ...? :class: dropdown

Installing software can be confusing. Here's a simple guide to making a sensible choice.

1. Are you using an {term}Environment Manager?
   If you are already using an environment manager, you should use that tool to install jupyter-book.

2. Are you willing to use an {term}Environment Manager?
   There are lots of environment managers to choose from. If you aren't sure which to choose, it is recommended to start with a Python virtual environment.

3. Otherwise ...
   pip can install packages into your home directory with

pip install -U jupyter-book>=2

:::{warning} Ignoring environment management :name: warning:env-management

Ignoring environment management can lead to confusion later when things break. It is recommended to use a virtual environment if you do not use an existing tool. ::: ::::

::::{grid} 1 2 2 2

:::{card} :header: Install with pip 🐍

In a virtual environment:

pip install "jupyter-book>=2"

:::

:::{card} :header: Install with mamba / conda 🔥

mamba install -c conda-forge \
"jupyter-book>=2"

:::

:::{card} :header: Install with pipx ⚙️

Never heard of pipx? See the documentation for more.

pipx install "jupyter-book>=2"

:::

:::{card} :header: Install with pixi 🔥

Never heard of pixi? See the documentation for more.

pixi add "jupyter-book>=2"

:::

:::{card} :header: Install with npm 🔥

Never heard of npm? See the documentation for more.

npm install -g "jupyter-book@>=2"

:::

::::