Tutorial

Welcome! Here’s a little tutorial, assuming you’re brand-new here. We’ll walk you through:

creating a virtual environment;
installing nbqa, and checking your installation;
running black on your notebook;
configuring nbqa.

Creating a virtual environment

Rather than using your system installation of Python, we recommend using a virtual environment so that your dependencies don’t clash with each other. Here’s one way to set one up using Conda - see this tutorial for other options.

Install the Miniconda distribution of Python;
Create a new virtual environment. Here, we’ll call it nbqa-env
```
conda create -n nbqa-env python=3.8 -y
```
Activate your virtual environment
```
conda activate nbqa-env
```

Install nbqa and black

Install nbqa and at least one Python code quality tool - here, we’ll use black
```
pip install -U nbqa black
```
Check your installation
```
nbqa --version
black --version
```

Neither of these commands should error.

Run nbqa black

Locate a Jupyter Notebook on your system. If you don’t have one, here is a nice one you can download.

Run the black formatter on your notebook via nbqa

nbqa black notebook.ipynb --line-length=96

Reload your notebook, and admire the difference!

Configuring nbqa

Rather than having to type --line-length=96 from the command-line for each notebook you want to reformat, you can configure nbqa in your pyproject.toml file. Open up your pyproject.toml file (or create one if you don’t have one already) and add in the following lines

[tool.black]
line-length = 96

Now, you’ll be able to run the command from the previous section with just

nbqa black notebook.ipynb

Much simpler!

See configuration for how to further configure how nbqa.