# Editor integration
## Emacs
Options include the following:
[wbolster/emacs-python-black](https://github.com/wbolster/emacs-python-black)
[proofit404/blacken](https://github.com/pythonic-emacs/blacken)
## 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 {doc}`Black’s HTTP server </usage_and_configuration/black_as_a_server>`, to avoid the startup cost on subsequent formats.
1. As external tool. 1. As file watcher.
### Built-in _Black_ integration
Install black.
`console $ 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.
`console $ pip install 'black[d]' `
Install [BlackConnect IntelliJ IDEs plugin](https://plugins.jetbrains.com/plugin/14321-blackconnect).
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:
1. Check Start local blackd instance when plugin loads. 1. Press the Detect button near Path input. The plugin should detect the blackd
executable.
In Trigger Settings section check Trigger 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 check Trigger when saving changed files.
### As external tool
Install black.
`console $ pip install black `
Locate your black installation folder.
On macOS / Linux / BSD:
`console $ which black /usr/local/bin/black # possible location `
On Windows:
`console $ 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.
`console $ pip install black `
Locate your black installation folder.
On macOS / Linux / BSD:
`console $ which black /usr/local/bin/black # possible location `
On Windows:
`console $ 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](https://plugins.jetbrains.com/plugin/7177-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](https://wingware.com/doc/edit/auto-reformatting). The detailed procedure is:
### Prerequistes
Wing IDE version 8.0+
Install black.
`console $ pip install black `
Make sure it runs from the command line, e.g.
`console $ 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) to Line after edit or Whole files before save.
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:
In menubar navigate to Project -> Project Properties -> Options.
Set Auto-Reformat from Use Preferences setting (default) to Line after edit or Whole files before save.
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.7+ support. It needs Python 3.7 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](https://github.com/junegunn/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](../contributing/release_process.md) 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](https://github.com/VundleVim/Vundle.vim):
`
Plugin 'psf/black'
`
and execute the following in a terminal:
`console
$ cd ~/.vim/bundle/black
$ git checkout origin/stable -b stable
`
##### Arch Linux
On Arch Linux, the plugin is shipped with the [python-black](https://archlinux.org/packages/community/any/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](https://github.com/psf/black/blob/stable/plugin/black.vim) and [autoload/black.vim](https://github.com/psf/black/blob/stable/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
To run _Black_ on a key press (e.g. F9 below), add this:
`
nnoremap <F9> :Black<CR>
`
### With ALE
Install [ale](https://github.com/dense-analysis/ale)
Install black
Add this to your vimrc:
`vim 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
`console
$ gedit <file_name>
`
1. Go to edit > preferences > plugins 1. Search for external tools and activate it. 1. In Tools menu -> Manage external tools 1. Add a new tool using + button. 1. Copy the below content to the code window.
`console
#!/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](https://marketplace.visualstudio.com/items?itemName=ms-python.python) ([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
Alternatively the pre-release [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) extension can be used which runs a [Language Server Protocol](https://langserver.org/) server for Black. Formatting is much more responsive using this extension, but the minimum supported version of Black is 22.3.0.
## SublimeText 3
Use [sublack plugin](https://github.com/jgirardet/sublack).
## Python LSP Server
If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom, Sublime Text, Visual Studio Code and many more), you can use the [Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the [python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin.
## Atom/Nuclide
Use [python-black](https://atom.io/packages/python-black) or [formatters-python](https://atom.io/packages/formatters-python).
## Gradle (the build tool)
Use the [Spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle) 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-code-format](https://github.com/Franccisco/thonny-black-code-format).