JupyterLab Code Formatter

3.0.3 · active · verified Fri Apr 17

jupyterlab-code-formatter is a JupyterLab plugin that integrates popular code formatters (like Black, isort, Ruff, yapf, autopep8) directly into the JupyterLab IDE. It allows users to format their Python code within notebooks and script files via a context menu, menu bar, or keyboard shortcuts. The current version, 3.0.3, is designed for JupyterLab 3.x and 4.x, leveraging its modern extension system. It maintains an active development cycle with regular updates.

Common errors

```
Error: Formatter 'black' not found. Please ensure 'black' is installed and available in your PATH.
```
cause The specific formatter (e.g., Black) is not installed in the Python environment where JupyterLab is running.

fix Install the missing formatter: `pip install black` (or `isort`, `ruff`, etc.). Restart JupyterLab after installation.
```
JupyterLab extension is not showing up or formatting options are missing from the menu.
```
cause The JupyterLab frontend did not properly load or enable the extension, or there's a version mismatch.

fix Check for version compatibility (`jupyterlab-code-formatter` and `jupyterlab`). If versions match, try running `jupyter lab build` in your terminal, then clear your browser cache and restart JupyterLab. Ensure you've installed formatters.
```
No module named 'jupyterlab_code_formatter' when I try to import it.
```
cause jupyterlab-code-formatter is a JupyterLab *extension* and is not meant to be imported directly into Python scripts by end-users. It's a server-side component for the JupyterLab frontend.

fix You do not need to `import jupyterlab_code_formatter` in your Python code. Install it via `pip` and interact with its features directly through the JupyterLab UI (right-click menu, Edit menu, keyboard shortcuts).

Warnings

breaking JupyterLab Code Formatter versions are tied to JupyterLab major versions. Version 3.x is for JupyterLab 3.x/4.x. If you are using JupyterLab 2.x, you need to install jupyterlab-code-formatter 2.x.
Fix: Ensure your `jupyterlab-code-formatter` version matches your `jupyterlab` major version (e.g., `jupyterlab_code_formatter>=3` for `jupyterlab>=3`). Upgrade JupyterLab if necessary or downgrade the extension.
gotcha The `jupyterlab_code_formatter` extension itself does not include the actual code formatters (like Black, isort, Ruff). You must install your desired formatters separately in the same Python environment where JupyterLab is running.
Fix: After installing `jupyterlab_code_formatter`, always run `pip install black isort ruff` (or your preferred formatters) to make them available to the extension.
gotcha After installing or updating the extension, you might need to rebuild your JupyterLab frontend for the changes to take effect, especially with older JupyterLab versions or complex environments. The `jupyter lab build` command is often helpful.
Fix: If the extension doesn't appear after restarting JupyterLab, try running `jupyter lab build` in your terminal and then restart JupyterLab again. Clear browser cache if issues persist.
gotcha Configuration for jupyterlab-code-formatter is done via JupyterLab's 'Advanced Settings Editor', not via Python code or separate config files in your user directory. Common issues include incorrect paths or enabled formatters.
Fix: Open 'Settings' > 'Advanced Settings Editor' in JupyterLab, then select 'Code Formatter'. Ensure 'formatOnSave' or specific formatters are enabled and paths are correct if you've customized them. Save changes and restart JupyterLab if necessary.

Install

pip install jupyterlab_code_formatter Install the extension
pip install black isort ruff Install desired formatters (example)

Quickstart

Install the extension and your preferred code formatters (e.g., black, isort, ruff). After installation, restart your JupyterLab server. The formatting options will appear in the right-click context menu within a notebook cell or file editor, under the 'Format Code' menu, or via the 'Edit' menu. You can also configure keyboard shortcuts and default formatters in JupyterLab's Advanced Settings Editor.

pip install jupyterlab_code_formatter
pip install black isort ruff
# Then, restart JupyterLab. Right-click on a cell or file to format.

view raw JSON →