Editor integration

PyCharm

  1. Install black.
$ pip install black
  1. 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
  1. Open External tools in PyCharm with File -> Settings -> Tools -> External Tools.
  2. 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$
  3. Format the currently opened file by selecting Tools -> External Tools -> black.
    • Alternatively, you can set a keyboard shortcut by navigating to Preferences -> Keymap -> External Tools -> External Tools - Black.
  4. Optionally, run Black on every file save:
    1. Make sure you have the File Watcher plugin installed.
    2. Go to Preferences -> 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: $FilePathRelativeToProjectRoot$
      • Working directory: $ProjectFileDir$

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 to 0)
  • g:black_linelength (defaults to 88)
  • g:black_skip_string_normalization (defaults to 0)
  • g:black_virtualenv (defaults to ~/.vim/black)

To install with vim-plug:

Plug 'ambv/black',

or with Vundle:

Plugin 'ambv/black'

or you can copy the plugin from 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'

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.

IPython 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.

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 File Watchers.