{"id":6008,"library":"nbqa","title":"nbqa: Run Code Quality Tools on Jupyter Notebooks","description":"nbqa is a command-line tool that allows you to run any standard Python code quality tool on Jupyter Notebooks. It robustly handles IPython magics, respects your existing configuration files (like `pyproject.toml`), and can lint both code and markdown cells. The current version is 1.9.1, with frequent minor point releases.","status":"active","version":"1.9.1","language":"python","source_language":"en","source_url":"https://github.com/nbQA-dev/nbQA","tags":["jupyter","notebook","linter","formatter","code quality","pre-commit","ci/cd"],"install":[{"cmd":"pip install nbqa","lang":"bash","label":"Basic Installation"},{"cmd":"pip install -U \"nbqa[toolchain]\"","lang":"bash","label":"With all supported linters/formatters"}],"dependencies":[{"reason":"nbqa requires Python 3.9 or higher.","package":"python","optional":false},{"reason":"Core dependency for functionality.","package":"autopep8","optional":false},{"reason":"Core dependency for functionality.","package":"ipython","optional":false},{"reason":"Core dependency for functionality.","package":"tokenize-rt","optional":false},{"reason":"Core dependency for configuration parsing.","package":"tomli","optional":false}],"imports":[],"quickstart":{"code":"# Install nbqa and a code quality tool (e.g., black)\npip install -U nbqa black\n\n# Create a dummy notebook (e.g., my_notebook.ipynb)\necho '{\n \"cells\": [\n  {\n   \"cell_type\": \"code\",\n   \"execution_count\": null,\n   \"metadata\": {},\n   \"outputs\": [],\n   \"source\": [\"import os\\n\\nx =  1 +  2\"]\n  }\n ],\n \"metadata\": {\n  \"kernelspec\": {\n   \"display_name\": \"Python 3\",\n   \"language\": \"python\",\n   \"name\": \"python3\"\n  },\n  \"language_info\": {\n   \"codemirror_mode\": {\n    \"name\": \"ipython\",\n    \"version\": 3\n   },\n   \"file_extension\": \".py\",\n   \"mimetype\": \"text/x-python\",\n   \"name\": \"python\",\n   \"nbconvert_exporter\": \"python\",\n   \"pygments_lexer\": \"ipython3\",\n   \"version\": \"3.9.0\"\n  }\n },\n \"nbformat\": 4,\n \"nbformat_minor\": 4\n}' > my_notebook.ipynb\n\n# Run black on the notebook using nbqa\nnbqa black my_notebook.ipynb\n\n# Expected output will show reformatting, e.g.:\n# reformatted my_notebook.ipynb\n# All done! ✨ 🍰 ✨ 1 file reformatted.\n\n# To verify changes (if you open the notebook, it should be formatted)\n# cat my_notebook.ipynb","lang":"bash","description":"This quickstart demonstrates how to install `nbqa` and `black`, then use `nbqa` to format a Jupyter Notebook. Remember to install the specific code quality tools (like `black`, `flake8`, `isort`) you wish to use alongside `nbqa`."},"warnings":[{"fix":"Review `nbqa`'s documentation on known limitations and how specific tool configurations interact with its conversion process. Consider alternative configuration methods via `pyproject.toml` or `nbqa`'s own `--nbqa-files` and `--nbqa-exclude` flags.","message":"nbqa converts code cells to temporary Python files for linting. This conversion process can cause certain tool-specific flags, such as `flake8`'s `--per-file-ignores`, to behave unexpectedly or not work perfectly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `--nbqa-dont-skip-bad-cells` cautiously for syntax errors. Be aware that magics like `%%time` or `%matplotlib inline` are generally ignored or cannot be processed by underlying tools.","message":"By default, nbqa skips cells with invalid syntax. While this can be overridden with the `--nbqa-dont-skip-bad-cells` flag, cells containing multi-line IPython magics or automagics (e.g., `%timeit`) will still not be processed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully manage your configuration sources. Prefer `pyproject.toml` for consistent project-wide settings and use command-line arguments only for temporary overrides or specific runs. Consult the documentation of the specific code quality tool for how it handles duplicate or conflicting arguments.","message":"When configuring `nbqa` via both `pyproject.toml` and command-line arguments, command-line arguments take precedence for `nbqa`'s own flags. For flags passed through to the underlying code quality tools, both sets of flags might be used, with `pyproject.toml` flags applied first. This can lead to tool-dependent or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For interactive in-notebook formatting, consider JupyterLab extensions like `jupyterlab_code_formatter`. `nbqa` is best utilized as a pre-commit check or a batch process.","message":"nbqa is designed primarily for command-line execution or integration into pre-commit hooks and CI/CD pipelines. It is not intended for real-time, interactive code quality checks directly within a running Jupyter Notebook or JupyterLab interface.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Manually review and update the versions of your `additional_dependencies` in your `.pre-commit-config.yaml` to ensure you are using the desired versions of code quality tools. Pinning versions is recommended for reproducibility.","message":"When using `nbqa` as a `pre-commit` hook, particularly with `additional_dependencies`, running `pre-commit autoupdate` will update the `nbqa` hook itself, but *not* the versions of the code quality tools (e.g., `black`, `isort`) specified in `additional_dependencies`. These must be updated manually for reproducibility.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.9.1':54 'allow':17 'cell':49 'ci/cd':69 'code':3,24,46,64 'command':13 'command-lin':12 'commit':68 'configur':38 'current':51 'exist':37 'file':39 'formatt':63 'frequent':56 'handl':32 'ipython':33 'jupyt':7,28,60 'like':40 'line':14 'lint':44 'linter':62 'magic':34 'markdown':48 'minor':57 'nbqa':1,9 'notebook':8,29,61 'point':58 'pre':67 'pre-commit':66 'pyproject.toml':41 'python':23 'qualiti':4,25,65 'releas':59 'respect':35 'robust':31 'run':2,20 'standard':22 'tool':5,15,26 'version':52","created_at":"2026-04-14T18:37:58.216146+00:00","updated_at":"2026-04-16T17:19:56.226817+00:00","problems":[{"fix":"Install the missing tool using pip; for example, `pip install black` or `pip install \"nbqa[toolchain]\"` to install all supported tools.","cause":"The underlying code quality tool (e.g., 'black', 'flake8', 'isort', 'mypy') that nbqa is trying to run has not been installed in the environment where nbqa is executed.","error":"ModuleNotFoundError: No module named 'black'"},{"fix":"Ensure nbqa is installed (`pip install nbqa`) and that your Python scripts directory (e.g., `~/.local/bin` on Linux/macOS or `Scripts` in your Python installation on Windows) is correctly added to your system's PATH. Restart your terminal after making changes.","cause":"The nbqa command-line tool is either not installed, or its installation directory is not included in your system's PATH environment variable.","error":"nbqa: command not found"},{"fix":"Inspect the code in the specified notebook cell for syntax errors or problematic IPython magics. You might need to adjust the code, or for certain magics, consider using `nbqa`'s `--nbqa-process-cells` flag. Upgrading both `nbqa` and `black` to their latest versions may also resolve compatibility issues.","cause":"The 'black' formatter, when invoked via nbqa, encountered a syntax error, an unparsable construct, or a specific IPython magic in the notebook cell at the reported line and column, preventing successful formatting.","error":"ERROR: cannot format <notebook_path>: Cannot parse: <line>:<col>: <error_message>"},{"fix":"Configure the linter to ignore these specific errors for notebooks. You can add `ignore = E302,E305` to your `pyproject.toml` or `.flake8` configuration file under the `[flake8]` section, or pass `--extend-ignore=E302,E305` directly to the `nbqa flake8` command.","cause":"Linter errors like E302 (expected blank lines) and E305 (expected blank lines after class/function definition) from tools like `flake8` are commonly triggered because nbqa converts notebook cells to temporary Python files, which can alter the contextual spacing and lead to false positives based on typical Python file conventions.","error":"E302 expected 2 blank lines, found 1"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"nbqa","cli_version":"nbqa 1.9.1","type":"library","homepage":null,"github":"https://github.com/nbQA-dev/nbQA","docs":"https://nbQA.readthedocs.io/en/latest/","changelog":null,"pypi":"https://pypi.org/project/nbqa/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-14","next_check":"2026-07-13","install_tag":null}}