Skip to content
Back to top
View this page

# Editor integration

## Emacs

Options include the following:

- wbolster/emacs-python-black

- proofit404/blacken

- Elpy.

## PyCharm/IntelliJ IDEA

There are several different ways you can use Black from PyCharm:

1. Using the built-in Black integration (PyCharm 2023.2 and later). This option is the simplest to set up.

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

3. As external tool.

4. As file watcher.

### Built-in Black integration

1. Install `black`.

       $ pip install black

2. Go to `Preferences or Settings -> Tools -> Black` and configure Black to your liking.

### As local server

1. Install Black with the `d` extra.

       $ pip install 'black[d]'

2. Install BlackConnect IntelliJ IDEs plugin.

3. Open plugin configuration in PyCharm/IntelliJ IDEA

   On macOS:

   `PyCharm -> Preferences -> Tools -> BlackConnect`

   On Windows / Linux / BSD:

   `File -> Settings -> Tools -> BlackConnect`

4. In `Local Instance (shared between projects)` section:

   1. Check `Start local blackd instance when plugin loads`.

   2. Press the `Detect` button near `Path` input. The plugin should detect the `blackd` executable.

5. In `Trigger Settings` section check `Trigger on code reformat` to enable code reformatting with Black.

6. Format the currently opened file by selecting `Code -> Reformat Code` or using a shortcut.

7. Optionally, to run Black on every file save:

   - In `Trigger Settings` section of plugin configuration check `Trigger when saving changed files`.

### As external tool

1. Install `black`.

       $ pip install black

2. Locate your `black` installation folder.

   On macOS / Linux / BSD:

       $ which black
       /usr/local/bin/black  # possible location

   On Windows:

       $ where black
       C:\Program Files\Python313\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`.

3. Open External tools in PyCharm/IntelliJ IDEA

   On macOS:

   `PyCharm -> Preferences -> Tools -> External Tools`

   On Windows / Linux / BSD:

   `File -> Settings -> Tools -> External Tools`

4. 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$"`

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

1. Install `black`.

       $ pip install black

2. Locate your `black` installation folder.

   On macOS / Linux / BSD:

       $ which black
       /usr/local/bin/black  # possible location

   On Windows:

       $ where black
       C:\Program Files\Python313\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`.

3. Make sure you have the File Watchers plugin installed.

4. 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:

1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`.

2. Set Auto-Reformat from `disable` (default) to `Line after edit` or `Whole files before save`.

3. Set Reformatter from `PEP8` (default) to `Black`.

### Project Properties

If you want to just reformat for a specific project and not intervene with Wing IDE global setting, follow these steps:

1. In menubar navigate to `Project -> Project Properties -> Options`.

2. Set Auto-Reformat from `Use Preferences setting` (default) to `Line after edit` or `Whole files before save`.

3. Set Reformatter from `Use Preferences setting` (default) to `Black`.

## 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 to `0`)

- `g:black_linelength` (defaults to `88`)

- `g:black_skip_string_normalization` (defaults to `0`)

- `g:black_skip_magic_trailing_comma` (defaults to `0`)

- `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)

- `g:black_use_virtualenv` (defaults to `1`)

- `g:black_target_version` (defaults to `""`)

- `g:black_quiet` (defaults to `0`)

- `g:black_preview` (defaults to `0`)

#### Installation

This plugin requires Vim 7.0+ built with Python 3.10+ support. It needs Python 3.10 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

1. Install `ale`

2. Install `black`

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

1. `Go to edit > preferences > plugins`

2. Search for `external tools` and activate it.

3. In `Tools menu -> Manage external tools`

4. Add a new tool using `+` button.

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

## 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  -'
    }

## Thonny

Use Thonny-black-formatter.