Using Black with Jupyter Notebooks

Black supports formatting Jupyter Notebooks (.ipynb files) natively.

Installation

To format Jupyter Notebooks, install Black with the jupyter extra:

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:

black notebook.ipynb

You can also format entire directories containing a mix of .py and .ipynb files:

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:

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:

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.3.1
    hooks:
      - id: black-jupyter
        language_version: python3.11

See the source version control integration docs for more examples of using Black with pre-commit.

GitHub Actions

Set the jupyter option to true.