Automatically run Black in PyCharm on Windows

Jostein Leira

Published in

Compendium

4 min readNov 2, 2021

(December 2021)

An updated and shorter version from December 2022 is here.

I often forget to run the code formatter before I commit code to git. This is bad since the following commits will contain irrelevant formatting changes.

I want the code formatter to run automatically. I have heard about git pre-commit hooks but never used them on Windows.

These are the installation steps:

Overview

Install a system Python on Windows
Create a virtual environment for the Black formatter
Add Black in PyCharm’s External tools (optional step)
Enable the File Watchers plugin in PyCharm

Install a system Python on Windows

You need Python installed on your system. Go to python.org and download and install if not already OK. You need to know the path to the python.exe file for the next step (create virtual environment below).

On Windows I never let any installation program add itself to the path if I can control it. Also valid for Python, so we must find the system python.exe file.

Open a Command Prompt window and run “dir \python.exe /s”:

C:\>dir \python.exe /s(ignore any virtual environment ones)(ignore Windows apps)This is the one:Directory of C:\Users\<user>\AppData\Local\Programs\Python\Python3930.08.2021  20:36           101 608 python.exe1 File(s)        101 608 bytes

Note the <full path> to python.exe, with your actual user name instead of <user>.

C:\Users\<user>\AppData\Local\Programs\Python\Python39

Check that the python.exe is the one you want by running it with the version option “-V”.

<full path>\python -V
Python 3.9.7

Create a virtual environment for the Black formatter

I always create a new virtual environment for new applications, not to mess with either the system Python or other applications.

Change the target path at the end to the one you want and run the command:

<full path>\python -m venv C:\Users\<user>\venv\black

Then install the black package in the new virtual environment.

C:\Users\<user>\venv\black\Scripts\pip install black

Add Black in PyCharm’s External tools

This is an optional step if you only want automatic formatting and not the option to run black from the PyCharm menu.

Add Balck to PyCharm’s External tools by going to Settings | Tools | External Tools. Choose + to create a new tool entry:

Settings | Tools | External Tools | + (Add)

Fill in the fields:

Name: Black
Program: C:\Users\<user>\venv\black\Scripts\black.exe
Arguments: "$FilePath$"

The new tool is now available from the main menu: Tools | External Tools | Black, if you want to reformat the current file.

Enable the File Watchers plugin in PyCharm

The File Watchers plugin is bundled with PyCharm. First, we need to enable the plugin. Choose the menu option Settings | Plugins | File Watchers | Enable.

Settings | Plugins | File Watchers | Enable

Then create a new file watcher by going to the menu option Settings | Tools | File Watchers | + (Add <custom> template).

New File Watchers dialog — Settings | Tools | File Watchers | + (Add)

Fill in the fields:

Name: Black
File type: Python
Scope: Project Files
Program: C:\Users\<user>\venv\black\Scripts\black
Arguments: "$FilePath$"
Output paths to refresh: "$FilePath$"
Uncheck all advanced options.

The File Watchers plugin will run black on your files when they change.