jupyter-black

library0.4.0pypypi✓ verified 85d ago

Jupyter Black is an extension for Jupyter Notebook and Jupyter Lab that automatically beautifies Python code in cells using the Black formatter. It aims to provide an uncompromising, consistent code style directly within the interactive notebook environment. The current version is 0.4.0, and the project is actively maintained with updates released as needed to support newer Jupyter and Python versions.

testing

pip install jupyter-black

github ↗package ↗

INSTALL

IMPORT

SIG · JUPYTER-BLACK

jupyter-black

testingpythonv0.4.0

Install

5.5s avg

Import

1931ms

Disk

79MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 2.115s · 84.8MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 5.5s · import 1.747s · 90MB

79MB installed

● package 79MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jupyter_black

✓ import jupyter_black

The primary module to import for programmatic loading.

To enable jupyter-black, simply import the library and call `jupyter_black.load()` in a code cell. This can be customized with `line_length`, `verbosity`, and `target_version` arguments. Once loaded, code cells will be formatted automatically upon execution. Alternatively, you can use the IPython magic command `%load_ext jupyter_black` for default settings.

import jupyter_black import black # Load the extension with default settings or custom configurations jupyter_black.load( line_length=88, # Default Black line length fast=True, # Optional: skip AST verification for speed target_version=black.TargetVersion.PY311 # Adjust to your Python version ) # Code in subsequent cells will be automatically formatted on execution def example_function ( arg1, arg2 = None ): ''' A poorly formatted function. ''' if arg2 is None: return arg1 else: return arg1 + arg2

Debug

Known issues

breakingJupyter Black version 0.4.0 and higher requires `jupyterlab >= 4` or `notebook >= 7`. If you are using older versions of Jupyter Notebook, you will encounter compatibility issues.

fix

Upgrade your JupyterLab to version 4+ or Jupyter Notebook to version 7+, or pin `jupyter-black` to an older version like `0.3.4` (e.g., `pip install jupyter-black==0.3.4`).

affects: >=0.4.0

gotchaJupyter Black will not format cells containing IPython automagics (e.g., `%%timeit`), non-Python cell magics (e.g., `%%writefile`), multiline magics, or code with invalid Python syntax. These cells will be skipped without formatting.

fix

Ensure cells contain valid Python syntax for formatting. For cells with magics or mixed content, manual formatting may be required, or the magics should be placed on separate lines if possible.

affects: All

gotchaThere are multiple Python packages or older projects with similar names (e.g., `nb_black`, `drillan/jupyter-black`). Ensure you are installing and using `n8henrie/jupyter-black` from PyPI.

fix

Always install using `pip install jupyter-black` (the pypi.org/project/jupyter-black package) and verify the GitHub repository `n8henrie/jupyter-black` for official documentation and updates.

affects: All

Errors

Common errors & fixes

zsh: no matches found: black[jupyter]

When installing Black with the Jupyter extra via pip in zsh, the brackets `[]` are interpreted by the shell and cause a 'no matches found' error.

fix

Escape the brackets with a backslash: `pip install black\[jupyter\]`. Note that `jupyter-black` (this library) is a separate project from Black's own Jupyter integration, and does not require this extra.

SyntaxError: invalid syntax (when expecting formatting)

If a Jupyter cell contains code with a `SyntaxError`, `jupyter-black` (like `black` itself) will not attempt to reformat it. It requires syntactically valid Python code to apply formatting.

fix

Correct any syntax errors in the cell. Once the code is syntactically valid, `jupyter-black` will format it on the next execution.

Extension 'jupyter_black' could not be loaded.

This error typically occurs if `jupyter-black` is not properly installed, or if there's a version mismatch between the extension and your Jupyter environment (e.g., trying to use it with very old Jupyter versions or incompatible Jupyter Server configurations).

fix

Ensure `jupyter-black` is installed in the correct environment (`pip install jupyter-black`). If issues persist, verify your JupyterLab/Notebook version meets the `jupyter-black` requirements (JupyterLab >=4 / Notebook >=7) or consider using an older `jupyter-black` version. Restarting the Jupyter kernel or server can also resolve transient loading issues.

Upgrade

Version history

0.4.0latest on PyPI · released Aug 30, 2024

Audit

Dependencies

pythonrequiredRequired for execution

jupyterlaboptionalFor JupyterLab integration (version >= 4)

notebookoptionalFor Jupyter Notebook integration (version >= 7)

blackrequiredThe underlying Python formatter

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/n8henrie/jupyter-black ↗

packagehttps://pypi.org/project/jupyter-black/ ↗