Editor integration¶
Emacs¶
Options include the following:
PyCharm/IntelliJ IDEA¶
There are several different ways you can use Black from PyCharm:
Using the built-in Black integration (PyCharm 2023.2 and later). This option is the simplest to set up.
As local server using the BlackConnect plugin. This option formats the fastest. It spins up Black’s HTTP server, to avoid the startup cost on subsequent formats.
As external tool.
As file watcher.
Built-in Black integration¶
Install
black
.$ pip install black
Go to
Preferences or Settings -> Tools -> Black
and configure Black to your liking.
As local server¶
Install Black with the
d
extra.$ pip install 'black[d]'
Install BlackConnect IntelliJ IDEs plugin.
Open plugin configuration in PyCharm/IntelliJ IDEA
On macOS:
PyCharm -> Preferences -> Tools -> BlackConnect
On Windows / Linux / BSD:
File -> Settings -> Tools -> BlackConnect
In
Local Instance (shared between projects)
section:Check
Start local blackd instance when plugin loads
.Press the
Detect
button nearPath
input. The plugin should detect theblackd
executable.
In
Trigger Settings
section checkTrigger on code reformat
to enable code reformatting with Black.Format the currently opened file by selecting
Code -> Reformat Code
or using a shortcut.Optionally, to run Black on every file save:
In
Trigger Settings
section of plugin configuration checkTrigger when saving changed files
.
As external tool¶
Install
black
.$ pip install black
Locate your
black
installation folder.On macOS / Linux / BSD:
$ which black /usr/local/bin/black # possible location
On Windows:
$ where black %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
Note that if you are using a virtual environment detected by PyCharm, this is an unneeded step. In this case the path to
black
is$PyInterpreterDirectory$/black
.Open External tools in PyCharm/IntelliJ IDEA
On macOS:
PyCharm -> Preferences -> Tools -> External Tools
On Windows / Linux / BSD:
File -> Settings -> Tools -> External Tools
Click the + icon to add a new external tool with the following values:
Name: Black
Description: Black is the uncompromising Python code formatter.
Program: <install_location_from_step_2>
Arguments:
"$FilePath$"
Format the currently opened file by selecting
Tools -> External Tools -> black
.Alternatively, you can set a keyboard shortcut by navigating to
Preferences or Settings -> Keymap -> External Tools -> External Tools - Black
.
As file watcher¶
Install
black
.$ pip install black
Locate your
black
installation folder.On macOS / Linux / BSD:
$ which black /usr/local/bin/black # possible location
On Windows:
$ where black %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
Note that if you are using a virtual environment detected by PyCharm, this is an unneeded step. In this case the path to
black
is$PyInterpreterDirectory$/black
.Make sure you have the File Watchers plugin installed.
Go to
Preferences or Settings -> Tools -> File Watchers
and click+
to add a new watcher:Name: Black
File type: Python
Scope: Project Files
Program: <install_location_from_step_2>
Arguments:
$FilePath$
Output paths to refresh:
$FilePath$
Working directory:
$ProjectFileDir$
In Advanced Options
Uncheck “Auto-save edited files to trigger the watcher”
Uncheck “Trigger the watcher on external changes”
Wing IDE¶
Wing IDE supports black
via Preference Settings for system wide settings and
Project Properties for per-project or workspace specific settings, as explained in
the Wing documentation on
Auto-Reformatting. The detailed
procedure is:
Prerequistes¶
Wing IDE version 8.0+
Install
black
.$ pip install black
Make sure it runs from the command line, e.g.
$ black --help
Preference Settings¶
If you want Wing IDE to always reformat with black
for every project, follow these
steps:
In menubar navigate to
Edit -> Preferences -> Editor -> Reformatting
.Set Auto-Reformat from
disable
(default) toLine after edit
orWhole files before save
.Set Reformatter from
PEP8
(default) toBlack
.
Project Properties¶
If you want to just reformat for a specific project and not intervene with Wing IDE global setting, follow these steps:
In menubar navigate to
Project -> Project Properties -> Options
.Set Auto-Reformat from
Use Preferences setting
(default) toLine after edit
orWhole files before save
.Set Reformatter from
Use Preferences setting
(default) toBlack
.
Vim¶
Official plugin¶
Commands and shortcuts:
:Black
to format the entire file (ranges not supported);you can optionally pass
target_version=<version>
with the same values as in the command line.
:BlackUpgrade
to upgrade Black inside the virtualenv;:BlackVersion
to get the current version of Black in use.
Configuration:
g:black_fast
(defaults to0
)g:black_linelength
(defaults to88
)g:black_skip_string_normalization
(defaults to0
)g:black_skip_magic_trailing_comma
(defaults to0
)g:black_virtualenv
(defaults to~/.vim/black
or~/.local/share/nvim/black
)g:black_use_virtualenv
(defaults to1
)g:black_target_version
(defaults to""
)g:black_quiet
(defaults to0
)g:black_preview
(defaults to0
)
Installation¶
This plugin requires Vim 7.0+ built with Python 3.9+ support. It needs Python 3.9 to be able to run Black inside the Vim process which is much faster than calling an external command.
vim-plug
¶
To install with vim-plug:
Black’s stable
branch tracks official version updates, and can be used to simply
follow the most recent stable version.
Plug 'psf/black', { 'branch': 'stable' }
Another option which is a bit more explicit and offers more control is to use
vim-plug
’s tag
option with a shell wildcard. This will resolve to the latest tag
which matches the given pattern.
The following matches all stable versions (see the Release Process section for documentation of version scheme used by Black):
Plug 'psf/black', { 'tag': '*.*.*' }
and the following demonstrates pinning to a specific year’s stable style (2022 in this case):
Plug 'psf/black', { 'tag': '22.*.*' }
Vundle¶
or with Vundle:
Plugin 'psf/black'
and execute the following in a terminal:
$ cd ~/.vim/bundle/black
$ git checkout origin/stable -b stable
Arch Linux¶
On Arch Linux, the plugin is shipped with the
python-black
package, so you
can start using it in Vim after install with no additional setup.
Vim 8 Native Plugin Management¶
or you can copy the plugin files from plugin/black.vim and autoload/black.vim.
mkdir -p ~/.vim/pack/python/start/black/plugin
mkdir -p ~/.vim/pack/python/start/black/autoload
curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim
Let me know if this requires any changes to work with Vim 8’s builtin packadd
, or
Pathogen, and so on.
Usage¶
On first run, the plugin creates its own virtualenv using the right Python version and
automatically installs Black. You can upgrade it later by calling :BlackUpgrade
and
restarting Vim.
If you need to do anything special to make your virtualenv work and install Black (for
example you want to run a version from main), create a virtualenv manually and point
g:black_virtualenv
to it. The plugin will use it.
If you would prefer to use the system installation of Black rather than a virtualenv, then add this to your vimrc:
let g:black_use_virtualenv = 0
Note that the :BlackUpgrade
command is only usable and useful with a virtualenv, so
when the virtualenv is not in use, :BlackUpgrade
is disabled. If you need to upgrade
the system installation of Black, then use your system package manager or pip–
whatever tool you used to install Black originally.
To run Black on save, add the following lines to .vimrc
or init.vim
:
augroup black_on_save
autocmd!
autocmd BufWritePre *.py Black
augroup end
To run Black on a key press (e.g. F9 below), add this:
nnoremap <F9> :Black<CR>
With ALE¶
Install
ale
Install
black
Add this to your vimrc:
let g:ale_fixers = {} let g:ale_fixers.python = ['black']
Gedit¶
gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit as
$ gedit <file_name>
Go to edit > preferences > plugins
Search for
external tools
and activate it.In
Tools menu -> Manage external tools
Add a new tool using
+
button.Copy the below content to the code window.
#!/bin/bash
Name=$GEDIT_CURRENT_DOCUMENT_NAME
black $Name
Set a keyboard shortcut if you like, Ex.
ctrl-B
Save:
Nothing
Input:
Nothing
Output:
Display in bottom pane
if you like.Change the name of the tool if you like.
Use your keyboard shortcut or Tools -> External Tools
to use your new tool. When you
close and reopen your File, Black will be done with its job.
Visual Studio Code¶
Use the Python extension (instructions).
Alternatively the pre-release Black Formatter extension can be used which runs a Language Server Protocol server for Black. Formatting is much more responsive using this extension, but the minimum supported version of Black is 22.3.0.
SublimeText¶
For SublimeText 3, use sublack plugin. For higher versions, it is recommended to use LSP as documented below.
Python LSP Server¶
If your editor supports the Language Server Protocol (Atom, Sublime Text, Visual Studio Code and many more), you can use the Python LSP Server with the python-lsp-black plugin.
Atom/Nuclide¶
Use python-black or formatters-python.
Gradle (the build tool)¶
Use the Spotless plugin.
Kakoune¶
Add the following hook to your kakrc, then run Black with :format
.
hook global WinSetOption filetype=python %{
set-option window formatcmd 'black -q -'
}