{"id":9058,"library":"jupyter-black","title":"Jupyter Black","description":"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.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/n8henrie/jupyter-black","tags":["jupyter","jupyterlab","black","formatter","code-quality","extension"],"install":[{"cmd":"pip install jupyter-black","lang":"bash","label":"Install jupyter-black"}],"dependencies":[{"reason":"Required for execution","package":"python","optional":false},{"reason":"For JupyterLab integration (version >= 4)","package":"jupyterlab","optional":true},{"reason":"For Jupyter Notebook integration (version >= 7)","package":"notebook","optional":true},{"reason":"The underlying Python formatter","package":"black","optional":false}],"imports":[{"note":"The primary module to import for programmatic loading.","symbol":"jupyter_black","correct":"import jupyter_black"}],"quickstart":{"code":"import jupyter_black\nimport black\n\n# Load the extension with default settings or custom configurations\njupyter_black.load(\n    line_length=88, # Default Black line length\n    fast=True, # Optional: skip AST verification for speed\n    target_version=black.TargetVersion.PY311 # Adjust to your Python version\n)\n\n# Code in subsequent cells will be automatically formatted on execution\ndef example_function ( arg1,  arg2 =  None ):\n    '''\n    A poorly formatted function.\n    '''\n    if  arg2  is None:\n        return arg1\n    else:    return arg1 + arg2","lang":"python","description":"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."},"warnings":[{"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`).","message":"Jupyter 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.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"Jupyter 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"There 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"zsh: no matches found: black[jupyter]"},{"fix":"Correct any syntax errors in the cell. Once the code is syntactically valid, `jupyter-black` will format it on the next execution.","cause":"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.","error":"SyntaxError: invalid syntax (when expecting formatting)"},{"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.","cause":"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).","error":"Extension 'jupyter_black' could not be loaded."}]}