{"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":"en","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,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}