docs: add dedicated Jupyter Notebooks guide (psf#5009)

toroleapinc · pre-commit-ci[bot] · cobaltt7 · web-flow · commit ce030cc0f0e3 · 2026-03-01T21:56:29.000-06:00
Co-authored-by: pre-commit-ci[bot] &lt;66853113+pre-commit-ci[bot]@users.noreply.github.com&gt;
Co-authored-by: cobalt &lt;61329810+cobaltt7@users.noreply.github.com&gt;
Co-authored-by: Varun Chawla &lt;34209028+veeceey@users.noreply.github.com&gt;
Co-authored-by: Akash &lt;jainaakash303@gmail.com&gt;
Co-authored-by: edvatar &lt;88481784+toroleapinc@users.noreply.github.com&gt;
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -8,7 +8,7 @@ repos:
         name: Check pre-commit rev in example
         language: python
         entry: python -m scripts.check_pre_commit_rev_in_example
-        files: '(CHANGES\.md|source_version_control\.md)$'
+        files: '(CHANGES|source_version_control|using_black_with_jupyter_notebooks)\.md$'
         additional_dependencies:
           - beautifulsoup4>=4.14.2
           - commonmark>=0.9.1
@@ -18,7 +18,7 @@ repos:
         name: Check black version in the basics example
         language: python
         entry: python -m scripts.check_version_in_basics_example
-        files: '(CHANGES\.md|the_basics\.md)$'
+        files: '(CHANGES|the_basics)\.md$'
         additional_dependencies:
           - beautifulsoup4>=4.14.2
           - commonmark>=0.9.1
diff --git a/CHANGES.md b/CHANGES.md
@@ -70,6 +70,7 @@
 - Expand preview style documentation with detailed examples for `wrap_comprehension_in`,
   `simplify_power_operator_hugging`, and `wrap_long_dict_values_in_parens` features
   (#4987)
+- Add detailed documentation for formatting Jupyter Notebooks (#5009)
 
 ## 26.1.0
 
diff --git a/docs/faq.md b/docs/faq.md
@@ -58,24 +58,14 @@ _Black_ is timid about formatting Jupyter Notebooks. Cells containing any of the
 following will not be formatted:
 
 - automagics (e.g. `pip install black`)
-- non-Python cell magics (e.g. `%%writefile`). These can be added with the flag
-  `--python-cell-magics`, e.g. `black --python-cell-magics writefile hello.ipynb`.
-- multiline magics, e.g.:
+- non-Python cell magics (e.g. `%%writefile`)
+- multiline magics
+- code which `IPython`'s `TransformerManager` would transform magics into
+- invalid syntax
 
-  ```python
-  %timeit f(1, \
-          2, \
-          3)
-  ```
-
-- code which `IPython`'s `TransformerManager` would transform magics into, e.g.:
-
-  ```python
-  get_ipython().system('ls')
-  ```
-
-- invalid syntax, as it can't be safely distinguished from automagics in the absence of
-  a running `IPython` kernel.
+See
+[Using _Black_ with Jupyter Notebooks](guides/using_black_with_jupyter_notebooks.md#cells-that-black-will-skip)
+for details.
 
 ## Why does Flake8 report warnings?
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -17,11 +17,14 @@ Also, you can try out _Black_ online for minimal fuss on the
 ## Installation
 
 _Black_ can be installed by running `pip install black`. It requires Python 3.10+ to
-run. If you want to format Jupyter Notebooks, install with
-`pip install "black[jupyter]"`.
+run.
 
 If you use pipx, you can install Black with `pipx install black`.
 
+If you want to format Jupyter Notebooks, install with `pip install "black[jupyter]"`.
+See the [Jupyter Notebooks guide](./guides/using_black_with_jupyter_notebooks.md) for
+more details.
+
 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
 
 `pip install git+https://github.com/psf/black`
diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -7,10 +7,12 @@ hidden:
 
 introducing_black_to_your_project
 using_black_with_other_tools
+using_black_with_jupyter_notebooks
 ```
 
 Wondering how to do something specific? You've found the right place! Listed below are
 topic specific guides available:
 
 - {doc}`introducing_black_to_your_project`
 - {doc}`using_black_with_other_tools`
+- {doc}`using_black_with_jupyter_notebooks`
diff --git a/docs/guides/using_black_with_jupyter_notebooks.md b/docs/guides/using_black_with_jupyter_notebooks.md
@@ -0,0 +1,134 @@
+# Using _Black_ with Jupyter Notebooks
+
+_Black_ supports formatting Jupyter Notebooks (`.ipynb` files) natively.
+
+## Installation
+
+To format Jupyter Notebooks, install _Black_ with the `jupyter` extra:
+
+```sh
+pip install "black[jupyter]"
+```
+
+```{note}
+Without the `jupyter` extra, _Black_ will not be able to format `.ipynb` files.
+```
+
+## Basic usage
+
+Once installed, you can format notebooks the same way you format Python files:
+
+```sh
+black notebook.ipynb
+```
+
+You can also format entire directories containing a mix of `.py` and `.ipynb` files:
+
+```sh
+black .
+```
+
+_Black_ will automatically detect Jupyter Notebooks by their `.ipynb` extension and
+format them accordingly.
+
+### Formatting via standard input
+
+If you're piping notebook content on standard input, use the `--ipynb` flag to tell
+_Black_ to treat the input as a Jupyter Notebook:
+
+```sh
+cat notebook.ipynb | black --ipynb -
+```
+
+## What is (and isn't) formatted
+
+_Black_ formats the Python code cells in your notebook while preserving:
+
+- Markdown cells
+- Cell outputs
+- Cell metadata
+- Notebook metadata
+
+Only the source code within Python code cells is reformatted.
+
+### Cells that _Black_ will skip
+
+_Black_ is cautious about formatting notebook cells. The following cells will **not** be
+formatted:
+
+- **Automagics** — e.g. `pip install black` (without the `%` prefix)
+- **Non-Python cell magics** — e.g.:
+  ```python
+  %%writefile script.py
+  print("hello")
+  ```
+- **Multiline magics** — e.g.:
+  ```python
+  %timeit f(1, \
+          2, \
+          3)
+  ```
+- **IPython internal calls** — code that `IPython`'s `TransformerManager` would
+  transform, e.g.:
+  ```python
+  get_ipython().system('ls')
+  ```
+- **Invalid syntax** — as it cannot be safely distinguished from automagics without a
+  running IPython kernel.
+
+If you notice a cell is not being formatted, it is likely because it contains one of the
+above constructs.
+
+Additionally, _Black_ cannot format Jupyter Notebooks with the `--line-ranges` option.
+
+### Cell magics
+
+_Black_ understands IPython magics, but is conservative about which cells it will
+format. By default, _Black_ recognizes standard IPython magics.
+
+#### Custom python cell magics
+
+If you use custom cell magics that contain Python code, you can tell _Black_ about them
+using the `--python-cell-magics` flag:
+
+```sh
+black --python-cell-magics writefile notebook.ipynb
+```
+
+This also works in `pyproject.toml`:
+
+```toml
+[tool.black]
+python-cell-magics = ["writefile", "my_custom_magic"]
+```
+
+## Integrations
+
+### pre-commit
+
+Simply replace the `black` hook with `black-jupyter`.
+
+```yaml
+repos:
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 26.1.0
+    hooks:
+      - id: black-jupyter
+        language_version: python3.11
+```
+
+See the [source version control integration](../integrations/source_version_control.md)
+docs for more examples of using Black with pre-commit.
+
+### GitHub Actions
+
+Set the `jupyter` option to `true`.
+
+```yaml
+- uses: psf/black@stable
+  with:
+    jupyter: true
+```
+
+See the [GitHub Actions integration](../integrations/source_version_control.md) docs for
+more examples of using Black with GitHub Actions.
diff --git a/docs/integrations/github_actions.md b/docs/integrations/github_actions.md
@@ -32,59 +32,74 @@ We recommend the use of the `@stable` tag, but per version tags also exist if yo
 that. Note that the action's version you select is independent of the version of _Black_
 the action will use.
 
-The version of _Black_ the action will use can be configured via `version` or read from
-the `pyproject.toml` file. `version` can be any
-[valid version specifier](https://packaging.python.org/en/latest/glossary/#term-Version-Specifier)
-or just the version number if you want an exact version. To read the version from the
-`pyproject.toml` file instead, set `use_pyproject` to `true`. This will first look into
-the `tool.black.required-version` field, then the `dependency-groups` table, then the
-`project.dependencies` array and finally the `project.optional-dependencies` table. The
-action defaults to the latest release available on PyPI. Only versions available from
-PyPI are supported, so no commit SHAs or branch names.
+### Versions
 
-If you want to include Jupyter Notebooks, _Black_ must be installed with the `jupyter`
-extra. Installing the extra and including Jupyter Notebook files can be configured via
-`jupyter` (default is `false`).
+The version of _Black_ the action will use can be configured via `version` or read from
+the `pyproject.toml` file. The action defaults to the latest release available on PyPI.
 
-You can also configure the arguments passed to _Black_ via `options` (defaults to
-`'--check --diff'`) and `src` (default is `'.'`). Please note that the
-[`--check` flag](labels/exit-code) is required so that the workflow fails if _Black_
-finds files that need to be formatted.
+`version` can be any
+[valid version specifier](https://packaging.python.org/en/latest/glossary/#term-Version-Specifier)
+or just the version number if you want an exact version.
 
-Here's an example configuration:
+If you want to match versions covered by Black's
+[stability policy](labels/stability-policy), you can use the compatible release operator
+(`~=`):
 
 ```yaml
 - uses: psf/black@stable
   with:
     options: "--check --verbose"
     src: "./src"
-    jupyter: true
-    version: "21.5b1"
+    version: "~= 22.0"
 ```
 
-If you want to match versions covered by Black's
-[stability policy](labels/stability-policy), you can use the compatible release operator
-(`~=`):
+To read the version from the `pyproject.toml` file instead, set `use_pyproject` to
+`true`. This will first look into the `tool.black.required-version` field, then the
+`dependency-groups` table, then the `project.dependencies` array and finally the
+`project.optional-dependencies` table. Note that this requires Python >= 3.11, so using
+the setup-python action may be required, for example:
 
 ```yaml
+- uses: actions/setup-python@v5
+  with:
+    python-version: "3.13"
 - uses: psf/black@stable
   with:
     options: "--check --verbose"
     src: "./src"
-    version: "~= 22.0"
+    use_pyproject: true
 ```
 
-If you want to read the version from `pyproject.toml`, set `use_pyproject` to `true`.
-Note that this requires Python >= 3.11, so using the setup-python action may be
-required, for example:
+Only versions available from PyPI are supported, so no commit SHAs or branch names.
+
+### Jupyter Notebooks
+
+If you want to include Jupyter Notebooks, it can be enabled by setting `jupyter` to
+`true` (default is `false`):
 
 ```yaml
-- uses: actions/setup-python@v5
+- uses: psf/black@stable
   with:
-    python-version: "3.13"
+    jupyter: true
+```
+
+See the [Jupyter Notebooks guide](../guides/using_black_with_jupyter_notebooks.md) for
+more details.
+
+### CLI Options
+
+You can also configure the arguments passed to _Black_ via `options` (defaults to
+`'--check --diff'`) and `src` (default is `'.'`). Please note that the
+[`--check` flag](labels/exit-code) is required so that the workflow fails if _Black_
+finds files that need to be formatted.
+
+Here's an example configuration:
+
+```yaml
 - uses: psf/black@stable
   with:
     options: "--check --verbose"
     src: "./src"
-    use_pyproject: true
+    jupyter: true
+    version: "21.5b1"
 ```
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
@@ -33,22 +33,20 @@ include Jupyter Notebooks. To use this hook, simply replace the hook's `id: blac
 
 ```yaml
 repos:
-  # Using this mirror lets us use mypyc-compiled black, which is about 2x faster
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 26.1.0
     hooks:
       - id: black-jupyter
-        # It is recommended to specify the latest version of Python
-        # supported by your project here, or alternatively use
-        # pre-commit's default_language_version, see
-        # https://pre-commit.com/#top_level-default_language_version
         language_version: python3.11
 ```
 
 ```{note}
 The `black-jupyter` hook became available in version 21.8b0.
 ```
 
+See the [Jupyter Notebooks guide](../guides/using_black_with_jupyter_notebooks.md) for
+more details.
+
 ## Excluding files with pre-commit
 
 When using pre-commit, there's an important distinction in how file exclusions work.
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
@@ -123,7 +123,9 @@ useful when piping source on standard input.
 #### `--python-cell-magics`
 
 When processing Jupyter Notebooks, add the given magic to the list of known python-
-magics. Useful for formatting cells with custom python magics.
+magics. Useful for formatting cells with custom python magics. See the
+[Jupyter Notebooks guide](../guides/using_black_with_jupyter_notebooks.md) for more
+details.
 
 #### `-x, --skip-source-first-line`
 
@@ -248,8 +250,8 @@ Each range must be specified as two integers connected by a `-`: `<START>-<END>`
 `<START>` and `<END>` integer indices are 1-based and inclusive on both ends.
 
 _Black_ may still format lines outside of the ranges for multi-line statements.
-Formatting more than one file or any ipynb files with this option is not supported. This
-option cannot be specified in the `pyproject.toml` config.
+Formatting more than one file or any Jupyter Notebooks with this option is not
+supported. This option cannot be specified in the `pyproject.toml` config.
 
 Example: `black --line-ranges=1-10 --line-ranges=21-30 test.py` will format lines from
 `1` to `10` and `21` to `30`.
diff --git a/scripts/check_pre_commit_rev_in_example.py b/scripts/check_pre_commit_rev_in_example.py
