← Back to Blog

[Python] Black Formatter 설치와 VS Code 설정

computer science > programming

2026-07-126 min read

#computer-science #programming #python #black #formatter #vscode #pyproject

공식 문서: Black documentation, Black Formatter for Visual Studio Code, Formatting Python in VS Code

Black Python code formatter logo

이미지 출처: Black GitHub repository. Black은 Python code를 일관된 형식으로 자동 정리하는 formatter이다.

Black이란?

Black은 Python source code의 모양을 일정한 규칙에 맞게 자동으로 바꾸는 code formatter이다. 들여쓰기, 공백, 줄바꿈, 괄호 배치, 문자열 따옴표 같은 형식을 사람이 일일이 맞추지 않아도 된다.

예를 들어 다음 code를 저장하면,

def greet(name,age):
    message='Hello, '+name
    return {"message":message,"age":age}

Black은 다음과 같이 정리한다.

def greet(name, age):
    message = "Hello, " + name
    return {"message": message, "age": age}

Black의 목적은 code의 동작을 바꾸는 것이 아니라, project 전체의 code style을 일관되게 만드는 것이다. 선택할 수 있는 style option을 의도적으로 적게 제공하기 때문에 팀원이 각자 다른 형식을 주장하는 시간을 줄일 수 있다.

Formatter와 linter의 차이

Formatter와 linter는 역할이 다르다.

도구역할예시
Formattercode 형식을 자동으로 수정Black
Linter오류 가능성, 안 쓰는 변수, style 위반 등을 검사Ruff, Pylint
Import sorterimport 순서를 정리Ruff, isort

Black은 code를 보기 좋게 정리하지만, 사용하지 않는 import나 논리 오류를 찾아주는 도구는 아니다. 또한 import 문 내부의 줄바꿈은 처리하지만 import 순서를 정렬하는 것이 주목적은 아니다.

실제 project에서는 Black을 formatter로 사용하고 Ruff 같은 linter를 함께 사용하는 구성이 일반적이다.

설치

가상환경 만들기

project마다 Black version을 관리하려면 먼저 가상환경을 만든다.

macOS와 Linux에서는 다음과 같이 실행한다.

python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell에서는 다음과 같이 실행한다.

py -m venv .venv
.\.venv\Scripts\Activate.ps1

VS Code terminal 앞에 (.venv)가 표시되면 가상환경이 활성화된 것이다.

pip로 설치

활성화된 가상환경에 Black을 설치한다.

python -m pip install black

설치가 끝나면 version을 확인한다.

python -m black --version

개발 dependency를 requirements-dev.txt로 관리한다면 다음처럼 기록할 수 있다.

black

설치는 다음 명령어로 재현한다.

python -m pip install -r requirements-dev.txt

uv로 설치

uv project에서는 Black을 개발용 dependency로 추가한다.

uv add --dev black

실행할 때는 project environment를 사용하는 uv run을 붙인다.

uv run black --version
uv run black .

팀 project에서는 Black을 project의 개발 dependency로 설치하고 version 정보가 담긴 lockfile을 commit하는 편이 안전하다. 개발자마다 서로 다른 Black version을 사용하면 일부 code의 formatting 결과가 달라질 수 있기 때문이다.

Terminal에서 먼저 실행하기

VS Code 자동 formatting을 설정하기 전에 terminal에서 Black이 정상 동작하는지 확인하면 문제를 분리하기 쉽다.

특정 파일 하나를 formatting한다.

python -m black main.py

src directory 전체를 formatting한다.

python -m black src

현재 project 전체를 formatting한다.

python -m black .

Black은 기본적으로 파일을 직접 수정한다. 수정하지 않고 변경 필요 여부만 검사하려면 --check를 사용한다.

python -m black --check .

어떻게 바뀌는지 diff만 확인하려면 --diff를 사용한다.

python -m black --diff .

두 option을 함께 사용할 수도 있다.

python -m black --check --diff .

--check는 formatting할 파일이 없으면 exit code 0, 변경이 필요하면 1을 반환하므로 CI에서 검사하기 좋다.

VS Code에서 Black Formatter 설치

VS Code에서는 Python extension과 Black Formatter extension을 설치한다.

  1. VS Code 왼쪽의 Extensions view를 연다.
  2. Python을 검색하고 Microsoft의 Python extension을 설치한다.
  3. Black Formatter를 검색하고 Microsoft의 Black Formatter extension을 설치한다.

Black Formatter extension ID는 다음과 같다.

ms-python.black-formatter

Microsoft Black Formatter extension icon

이미지 출처: Microsoft Black Formatter GitHub repository. VS Code Marketplace에서 publisher가 Microsoft이고 extension ID가 ms-python.black-formatter인지 확인한다.

command line에서 설치한다면 다음 명령어를 사용할 수 있다.

code --install-extension ms-python.python
code --install-extension ms-python.black-formatter

Black Formatter extension에는 Black 실행 파일이 포함되어 있어 별도의 package 설치 없이도 formatting할 수 있다. 다만 팀에서 같은 Black version을 재현하려면 project 가상환경에 Black을 설치하고 그 환경을 사용하도록 설정하는 편이 명확하다.

VS Code에서 Python interpreter 선택

가상환경을 만들었다면 VS Code가 그 환경을 사용하도록 선택한다.

  1. Command Palette를 연다.
    • Windows/Linux: Ctrl+Shift+P
    • macOS: Cmd+Shift+P
  2. Python: Select Interpreter를 실행한다.
  3. project의 .venv Python을 선택한다.

대략 다음과 같은 경로가 표시된다.

macOS/Linux: .venv/bin/python
Windows:     .venv\Scripts\python.exe

선택한 interpreter는 Python 실행, package 탐색, formatter environment를 결정할 때 사용된다.

Black을 기본 formatter로 지정

Python 파일을 연 뒤 editor에서 마우스 오른쪽 버튼을 누르고 다음 menu를 선택한다.

Format Document With...
  -> Configure Default Formatter...
  -> Black Formatter

또는 Command Palette에서 Preferences: Open Workspace Settings (JSON)을 실행하고 .vscode/settings.json에 다음 내용을 작성한다.

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  }
}

이제 Python 파일에서 Format Document를 실행하면 Black이 동작한다.

운영체제Format Document 단축키
WindowsShift+Alt+F
macOSShift+Option+F
LinuxCtrl+Shift+I

저장할 때 자동 formatting하기

저장할 때마다 Black을 실행하려면 editor.formatOnSave를 활성화한다.

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.formatOnPaste": false,
    "editor.formatOnSaveMode": "file"
  }
}

이 설정은 Python 파일에만 적용된다. JavaScript나 Markdown 등 다른 언어의 formatter 설정에는 영향을 주지 않는다.

Black은 기본적으로 파일 전체를 formatting한다. 따라서 선택 영역만 formatting하는 Format Selection은 기대한 대로 동작하지 않을 수 있다.

VS Code에서는 editor.formatOnSaveMode를 file로 두고 저장할 때 파일 전체를 formatting하는 흐름이 가장 단순하다.

project에 권장하는 VS Code 설정

project의 .vscode/settings.json을 repository에 commit하면 팀원이 같은 editor 설정을 공유할 수 있다.

가상환경에 설치한 Black을 우선 사용하려면 다음처럼 작성한다.

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.formatOnPaste": false,
    "editor.formatOnSaveMode": "file"
  },
  "black-formatter.importStrategy": "fromEnvironment"
}

black-formatter.importStrategy의 차이는 다음과 같다.

값의미
useBundledVS Code extension에 포함된 Black을 사용하며 기본값이다.
fromEnvironment선택된 Python environment에 설치된 Black을 우선 사용한다.

fromEnvironment로 설정했지만 선택한 가상환경에서 Black을 찾지 못하면 extension에 포함된 version으로 fallback할 수 있다. 따라서 .venv가 선택되어 있는지와 그 환경에 Black이 설치되어 있는지를 함께 확인해야 한다.

extension이 사용할 실행 경로를 직접 지정할 수도 있다.

{
  "black-formatter.path": ["${workspaceFolder}/.venv/bin/black"]
}

하지만 이 경로는 Windows와 macOS/Linux에서 다르다. 여러 운영체제가 함께 작업하는 repository에서는 interpreter와 fromEnvironment 조합이 더 이식성이 좋다.

pyproject.toml로 Black 설정 공유

Black 설정은 project root의 pyproject.toml에 작성한다.

[tool.black]
line-length = 88
target-version = ["py311"]
include = '\.pyi?$'
extend-exclude = '''
(
  ^/generated/
  | .*_pb2.py
)
'''

주요 option은 다음과 같다.

option의미
line-length한 줄의 기준 길이이며 기본값은 88이다.
target-versionformatting 결과가 지원해야 하는 Python version이다.
includeformatting 대상으로 포함할 파일 pattern이다.
extend-exclude기본 제외 목록에 추가할 파일과 directory pattern이다.

target-version은 project가 지원하는 Python version에 맞춘다. 예를 들어 Python 3.11 이상만 지원한다면 py311로 설정할 수 있다.

[project]
requires-python = ">=3.11"

[tool.black]
line-length = 88
target-version = ["py311"]

Black은 별도의 option이 없으면 [project]의 requires-python 정보에서 target version을 추론할 수도 있다.

줄 길이 같은 project 규칙은 개인 VS Code 설정이 아니라 pyproject.toml에 두어야 terminal, editor, CI가 같은 결과를 만든다.

VS Code의 black-formatter.args에 --line-length를 직접 넣을 수도 있다.

{
  "black-formatter.args": ["--line-length", "100"]
}

하지만 이 설정은 VS Code에서만 적용될 수 있으므로 project 공통 규칙은 pyproject.toml에 두는 것이 좋다.

formatting을 일부 제외하기

한 줄만 Black의 formatting에서 제외하려면 # fmt: skip을 붙인다.

matrix = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]  # fmt: skip

여러 줄로 된 구간을 제외하려면 # fmt: off와 # fmt: on을 사용한다.

# fmt: off
TABLE = {
    "short":    1,
    "very_long": 2,
}
# fmt: on

이 기능은 사람이 맞춘 정렬이 의미를 전달하거나 자동 생성 code와 함께 작업할 때 유용하다. 다만 예외가 많아지면 formatting의 일관성이 사라지므로 필요한 구간에만 제한적으로 사용한다.

자주 발생하는 문제

저장해도 formatting되지 않는 경우

다음 항목을 순서대로 확인한다.

  1. 현재 파일의 language mode가 Python인지 확인한다.
  2. Microsoft의 Black Formatter extension이 설치되고 활성화되어 있는지 확인한다.
  3. [python].editor.defaultFormatter가 ms-python.black-formatter인지 확인한다.
  4. [python].editor.formatOnSave가 true인지 확인한다.
  5. Python: Select Interpreter에서 project의 .venv를 선택한다.
  6. Python 문법 오류가 없는지 확인한다.

문제가 계속되면 Command Palette에서 Output: Focus on Output을 실행한 뒤 Black Formatter log를 확인한다. formatter server를 다시 시작하려면 다음 command를 실행한다.

Black Formatter: Restart

여러 formatter 중 하나를 고르라는 경우

Ruff Formatter, autopep8 등 여러 formatter extension이 설치되어 있으면 VS Code가 기본 formatter를 묻는다. Python 파일에서 Format Document With...를 실행하고 Black Formatter를 기본값으로 지정한다.

terminal에서는 되는데 VS Code에서는 안 되는 경우

terminal이 활성화한 가상환경과 VS Code가 선택한 interpreter가 다를 가능성이 크다.

terminal에서 경로를 확인한다.

macOS/Linux:

which python
python -m black --version

Windows PowerShell:

Get-Command python
python -m black --version

출력된 Python 경로와 VS Code에서 선택한 .venv가 같은지 비교한다.

일부 code만 선택해서 formatting할 수 없는 경우

Black은 파일 전체 formatting을 기본으로 설계되었다. 선택한 부분만 바꾸기보다 파일 전체에 같은 규칙을 적용하는 것이 Black의 사용 방식에 가깝다.

추천 project 구성

my-project/
  .vscode/
    settings.json
  .venv/              # Git에 commit하지 않음
  src/
    main.py
  tests/
  .gitignore
  pyproject.toml

.gitignore에는 가상환경을 추가한다.

.venv/

.vscode/settings.json에는 저장 시 formatting 설정을 둔다.

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.formatOnPaste": false,
    "editor.formatOnSaveMode": "file"
  },
  "black-formatter.importStrategy": "fromEnvironment"
}

pyproject.toml에는 모든 환경이 공유할 Black 규칙을 둔다.

[tool.black]
line-length = 88
target-version = ["py311"]

정리

VS Code에서 Black을 사용하는 기본 흐름은 다음과 같다.

1. project에 .venv 생성
2. 가상환경에 Black 설치
3. VS Code에서 .venv interpreter 선택
4. Microsoft Black Formatter extension 설치
5. Black을 Python 기본 formatter로 지정
6. editor.formatOnSave 활성화
7. 공통 규칙은 pyproject.toml에 작성
8. CI에서는 black --check . 실행

처음에는 다음 설정만으로도 충분하다.

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
  }
}

Black을 도입하면 formatting을 사람이 검토하는 대신 도구에 맡길 수 있다. 그 결과 code review에서는 공백이나 줄바꿈보다 code의 동작과 설계에 더 집중할 수 있다.