nbqa

What it is and what it does

nbqa is a bridge that lets you run any standard Python code quality tool directly on Jupyter Notebooks. Instead of extracting code manually or writing custom scripts, you point nbqa at a notebook and a linter—black, isort, mypy, pylint, flake8, pyupgrade, ruff, or others—and it handles the notebook format transparently. It extracts code cells, runs the tool, and writes changes back while preserving the notebook structure.

The package is designed for teams that treat notebooks as production code and want to enforce the same style and quality standards across both .py files and .ipynb files. It respects your existing tool configuration files, handles IPython magics robustly so they don't break linting, preserves trailing semicolons in quiet mode, and can lint both code and markdown cells. It also works with .md files saved via Jupytext.

Use it for:

• Enforce consistent code style (black, autopep8) across all notebooks in a data science project without manual reformatting.
• Run type checking (mypy) or linting (pylint, ruff) on notebook code to catch bugs before they reach production.
• Upgrade Python syntax (pyupgrade) and sort imports (isort) across a collection of notebooks as part of CI/CD.
• Set up pre-commit hooks to automatically format and lint notebooks before they are committed to version control.
• Lint markdown documentation cells in notebooks to maintain consistent documentation formatting.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Runs standard Python linters and formatters (ruff, black, isort, mypy, pylint, flake8, pyupgrade, and others) on Jupyter Notebook code and markdown cells while handling IPython magics and respecting configuration files.

Yes. nbqa solves a genuine problem—applying code quality tools to notebooks—with low install friction, active maintenance, no known vulnerabilities, and a permissive license. It is widely used in production projects and integrates cleanly into CI/CD and pre-commit workflows. Install it if your team uses Jupyter notebooks and wants to enforce the same code standards as your .py files.

Install

nbqa on PyPI

pip install nbqa

uv add nbqa

poetry add nbqa

Installing nbqa

Before you install

Low friction install with four runtime dependencies (autopep8, ipython, tokenize-rt, tomli). The project is actively maintained with a recent commit on 2026-08-10 and 1203 repository stars, indicating stable ongoing development.

License in practice

MIT license is permissive, allowing use in commercial and private projects with minimal restrictions—only requiring license attribution.

Quickstart

pip install nbqa
nbqa black my_notebook.ipynb
nbqa isort my_notebook.ipynb --float-to-top
nbqa mypy my_notebook.ipynb

Requires Python 3.9 or later. Individual linters (black, isort, mypy, etc.) must be installed separately or via the optional 'toolchain' extra.

Verify before relying

• Whether the package works with all versions of Jupyter/IPython or has specific compatibility constraints beyond Python 3.9.
• Performance characteristics when processing large notebooks or running multiple linters in sequence.
• Whether markdown cell linting requires additional dependencies beyond those listed.

Package facts

Evidence: nbqa-1.9.1-py3-none-any.whl

Keywords: jupyter, notebook, format, lint

Tags

More Quality Assurance packages