Editor integration¶
PyCharm/IntelliJ IDEA¶
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
.
Optionally, run Black on every file save:
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 supports black via the OS Commands tool, as explained in the Wing documentation on pep8 formatting. The detailed procedure is:
Install
black
.$ pip install black
Make sure it runs from the command line, e.g.
$ black --help
In Wing IDE, activate the OS Commands panel and define the command black to execute black on the currently selected file:
Use the Tools -> OS Commands menu selection
click on + in OS Commands -> New: Command line..
Title: black
Command Line: black %s
I/O Encoding: Use Default
Key Binding: F1
[x] Raise OS Commands when executed
[x] Auto-save files before execution
[x] Line mode
Select a file in the editor and press F1 , or whatever key binding you selected in step 3, to reformat the file.
Vim¶
Official plugin¶
Commands and shortcuts:
:Black
to format the entire file (ranges not supported);:BlackUpgrade
to upgrade Black inside the virtualenv;:BlackVersion
to get the current version of Black inside the virtualenv.
Configuration:
g:black_fast
(defaults to0
)g:black_linelength
(defaults to88
)g:black_skip_string_normalization
(defaults to0
)g:black_virtualenv
(defaults to~/.vim/black
or~/.local/share/nvim/black
)g:black_quiet
(defaults to0
)
To install with vim-plug:
Plug 'psf/black', { 'branch': 'stable' }
or with Vundle:
Plugin 'psf/black'
and execute the following in a terminal:
$ cd ~/.vim/bundle/black
$ git checkout origin/stable -b stable
or you can copy the plugin from plugin/black.vim.
mkdir -p ~/.vim/pack/python/start/black/plugin
curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
Let me know if this requires any changes to work with Vim 8’s builtin packadd
, or
Pathogen, and so on.
This plugin requires Vim 7.0+ built with Python 3.6+ support. It needs Python 3.6 to be able to run Black inside the Vim process which is much faster than calling an external command.
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.
To run Black on save, add the following line to .vimrc
or init.vim
:
autocmd BufWritePre *.py execute ':Black'
To run Black on a key press (e.g. F9 below), add this:
nnoremap <F9> :Black<CR>
How to get Vim with Python 3.6? On Ubuntu 17.10 Vim comes with Python 3.6 by
default. On macOS with Homebrew run: brew install vim
. When building Vim from source,
use: ./configure --enable-python3interp=yes
. There’s many guides online how to do
this.
I get an import error when using Black from a virtual environment: If you get an error message like this:
Traceback (most recent call last):
File "<string>", line 63, in <module>
File "/home/gui/.vim/black/lib/python3.7/site-packages/black.py", line 45, in <module>
from typed_ast import ast3, ast27
File "/home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/ast3.py", line 40, in <module>
from typed_ast import _ast3
ImportError: /home/gui/.vim/black/lib/python3.7/site-packages/typed_ast/_ast3.cpython-37m-x86_64-linux-gnu.so: undefined symbool: PyExc_KeyboardInterrupt
Then you need to install typed_ast
and regex
directly from the source code. The
error happens because pip
will download Python wheels if
they are available. Python wheels are a new standard of distributing Python packages and
packages that have Cython and extensions written in C are already compiled, so the
installation is much more faster. The problem here is that somehow the Python
environment inside Vim does not match with those already compiled C extensions and these
kind of errors are the result. Luckily there is an easy fix: installing the packages
from the source code.
The two packages that cause the problem are:
Now remove those two packages:
$ pip uninstall regex typed-ast -y
And now you can install them with:
$ pip install --no-binary :all: regex typed-ast
The C extensions will be compiled and now Vim’s Python environment will match. Note that
you need to have the GCC compiler and the Python development files installed (on
Ubuntu/Debian do sudo apt-get install build-essential python3-dev
).
If you later want to update Black, you should do it like this:
$ pip install -U black --no-binary regex,typed-ast
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).
SublimeText 3¶
Use sublack plugin.
Jupyter Notebook Magic¶
Use blackcellmagic.
Python Language Server¶
If your editor supports the Language Server Protocol (Atom, Sublime Text, Visual Studio Code and many more), you can use the Python Language Server with the pyls-black plugin.
Atom/Nuclide¶
Use python-black or formatters-python.
Kakoune¶
Add the following hook to your kakrc, then run Black with :format
.
hook global WinSetOption filetype=python %{
set-option window formatcmd 'black -q -'
}