Editor integration¶
Emacs¶
Use proofit404/blacken or Elpy.
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
- 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
.
- Alternatively, you can set a keyboard shortcut by navigating to
Optionally, run Black on every file save:
- Make sure you have the File Watcher 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$
- Uncheck “Auto-save edited files to trigger the watcher”
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¶
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
)
To install with vim-plug:
Plug 'psf/black'
or with Vundle:
Plugin 'psf/black'
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/master/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 master), 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 --with-python3
. When building
Vim from source, use: ./configure --enable-python3interp=yes
. There’s many guides
online how to do this.
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.
Kakoune¶
Add the following hook to your kakrc, then run black with :format
.
hook global WinSetOption filetype=python %{
set-option window formatcmd 'black -q -'
}
Other editors¶
Other editors will require external contributions.
Patches welcome! ✨ 🍰 ✨
Any tool that can pipe code through Black using its stdio mode (just
use -
as the file name).
The formatted code will be returned on stdout (unless --check
was passed). Black
will still emit messages on stderr but that shouldn’t affect your use case.
This can be used for example with PyCharm’s or IntelliJ’s File Watchers.