Skip to content
Back to top
View this page

# 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.:

      %%writefile script.py
      print("hello")

- Multiline magics — e.g.:

      %timeit f(1, \
              2, \
              3)

- IPython internal calls — code that `IPython`’s `TransformerManager` would transform, e.g.:

      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`:

    [tool.black]
    python-cell-magics = ["writefile", "my_custom_magic"]

## Integrations

### pre-commit

Simply replace the `black` hook with `black-jupyter`.

    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`.

    - uses: psf/black@stable
      with:
        jupyter: true

See the GitHub Actions integration docs for more examples of using Black with GitHub Actions.