Configuration

You can configure nbQA either at the command line, or by using a pyproject.toml file. We’ll see some examples below.

Note

Please note that if you pass the same option via both the pyproject.toml file and via the command-line, the command-line will take precedence.

Preview / CI

To preview changes without modifying your notebook, using the --nbqa-diff flag. The return code will be 1 if nbQA would’ve modified any of your notebooks, and 0 otherwise.

Note

You should not use -nbqa-diff alongside tools such as flake8 which only check your code. Instead, use it with formatters such as isort.

Extra flags

If you wish to pass extra flags (e.g. --extend-ignore E203 to flake8) you can either run

nbqa flake8 my_notebook.ipynb --extend-ignore E203

or you can put the following in your pyproject.toml file

[tool.nbqa.addopts]
flake8 = [
    "--extend-ignore=E203"
]

Note

If you specify extra flags via both the pyproject.toml file and the command-line, both will be passed on to the underlying command-line tool, with the options specified in pyproject.toml passed first. In this case the exact behaviour will depend on the tool and the option in question. It’s common that subsequent flags override earlier ones, but check the documentation for the tool and option in question to be sure.

Cell magics

By default, nbQA will ignore line magics (e.g. %matplotlib inline), as well as most cell magics. To process code in cells with cell magics, you can use the --nbqa-process-cells CLI argument. E.g. to process code within %%add_to cell magics, use

nbqa black my_notebook.ipynb --nbqa-process-cells add_to

or use the process_cells option in your pyproject.toml file:

[tool.nbqa.process_cells]
black = ["add_to"]

Include / exclude

To include or exclude notebooks from being processed, we recommend using nbQA’s own --nbqa-files and --nbqa-exclude flags. These take regex patterns and match posix-like paths, exactly like the same options from pre-commit. These can be set from the command-line with the --nbqa-files and --nbqa-exclude flags, or in your .pyproject.toml file in the [tool.nbqa.files] and [tool.nbqa.exclude] sections.

Say you’re running nbqa isort on a directory my_directory. Here are some examples of how to include/exclude files:

exclude notebooks in my_directory whose name starts with poc_:
[tool.nbqa.exclude] isort = "^my_directory/poc_"

exclude notebooks in subdirectory my_directory/my_subdirectory:

[tool.nbqa.exclude]
isort = "^my_directory/my_subdirectory/"

only include notebooks in my_directory whose name starts with EDA:
[tool.nbqa.files] isort = "^my_directory/EDA"

All the above examples can equivalently be run from the command-line, e.g. as

nbqa isort my_directory --nbqa-exclude ^my_directory/poc_

Don’t skip bad cells

By default, nbQA will skip cells with invalid syntax. To process cells with syntax errors, you can use the --nbqa-dont-skip-bad-cells CLI argument.

This can be set from the command-line with the --nbqa-dont-skip-bad-cells flag, or in your .pyproject.toml file in the [tool.nbqa.dont_skip_bad_cells] section.

For example, to process “bad” cells when running black on notebook.ipynb, you could add the following to your pyproject.toml file:

[tool.nbqa.dont_skip_bad_cells]
black = true

or, from the command-line:

nbqa black notebook.ipynb --nbqa-dont-skip-bad-cells

Skip cells based on celltags

You can skip cells based on the celltags in their metadata using the --nbqa-skip-celltags CLI argument.

For example, to skip cells which contain either the skip-flake8 or flake8-skip tags, you could add the following to your pyproject.toml file:

[tool.nbqa.skip_celltags]
black = ["skip-flake8", "flake8-skip"]

or, from the command-line:

nbqa black notebook.ipynb --nbqa-skip-celltags=skip-flake8,flake8-skip

Process markdown cells

You can process markdown cells (instead of code cells) by using the --nbqa-md CLI argument.

This is useful when running tools which run on markdown files, such as blacken-docs.

For example, you could add the following to your pyproject.toml file:

[tool.nbqa.md]
blacken-docs = true

or, from the command-line:

nbqa blacken-docs notebook.ipynb --nbqa-md

Shell commands

By default, nbQA runs a command command as python -m command. To instead run it as command (e.g. flake8heavened, which can’t be run as python -m flake8heavened), you could add the following to your pyproject.toml file:

[tool.nbqa.shell]
flake8heavened = true

or, from the command-line:

$ nbqa flake8heavened my_notebook.ipynb --nbqa-shell