[Python] 🔍 Pylint로 Python 코드 품질 관리하기: 설치부터 CI/CD 연동까지

Pylint는 Python 코드의 오류 검출, PEP 8 스타일 위반, 코드 복잡도 분석을 수행하는 정적 분석 도구입니다. 단순한 스타일 검사를 넘어 잠재적 버그까지 탐지하며, 10점 만점 품질 점수를 제공합니다. 이 글에서는 Pylint의 기본 사용법부터 .pylintrc 설정, VSCode 연동, pre-commit CI/CD 통합까지 실무에서 바로 활용할 수 있도록 정리합니다.

🔍 Pylint란?

Pylint는 Python 코드를 실행하지 않고도 품질 문제를 탐지하는 정적 코드 분석(static analysis) 도구입니다. 단순한 스타일 검사기를 넘어, 런타임 이전에 발견하기 어려운 버그와 잠재적 오류까지 잡아냅니다.

주요 검사 항목은 다음과 같습니다:

• 문법 오류 및 잠재적 버그 — 정의되지 않은 변수, self 누락, 잘못된 import 등
• PEP 8 코딩 표준 위반 — 명명 규칙(snake_case, PascalCase), 줄 길이, 공백 등
• 코드 복잡도 — 중복 코드, 너무 긴 함수, 지나치게 많은 인자 등
• 문서화 부재 — docstring 미작성 경고
• 10점 만점 품질 점수 — 코드 전체의 상태를 수치로 확인

Tip: Pylint의 경고가 절대적인 기준은 아닙니다. 의도된 코드가 경고를 받을 수 있으므로, 프로젝트 상황에 맞게 규칙을 조정하는 것이 중요합니다.

⚖️ Linter vs Formatter 차이

코드 품질 도구를 처음 접할 때 가장 혼란스러운 부분이 Linter와 Formatter의 차이입니다.

📊 Python 코드 품질 도구 비교

실무에서 자주 함께 언급되는 4가지 도구를 비교합니다.

1
2
3
4

Flake8 ─ 스타일 검사 → 오류 보고
Pylint ─ 심층 분석   → 오류 보고 + 개선 제안 + 품질 점수
Black  ─ 자동 포맷팅 → 코드 직접 수정
Ruff   ─ lint + format → 위 세 도구를 대부분 대체

Tip: 2026년 현재는 Ruff 단독 사용으로 lint·format·import 정리까지 처리하는 방식이 증가 중입니다. 하지만 Pylint는 Ruff가 탐지하지 못하는 심층 분석(코드 냄새, 복잡도, 품질 점수)에서 여전히 강점이 있습니다.

🚀 설치 및 기본 사용법

설치

1

pip install pylint

가상 환경을 사용하는 경우 환경 활성화 후 설치합니다.

1
2
3

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install pylint

파일 분석

1
2
3
4
5
6
7
8

# 단일 파일 분석
pylint my_script.py

# 모듈 전체 분석
pylint my_package/

# 여러 파일 동시 분석
pylint src/main.py src/utils.py

출력 결과 예시

1
2
3
4
5
6

my_script.py:5:0: C0304: Final newline missing (missing-final-newline)
my_script.py:10:4: W0611: Unused import os (unused-import)
my_script.py:15:0: E1101: Module 'os' has no 'pathh' member (no-member)

-----------------------------------
Your code has been rated at 6.50/10

출력 형식은 파일명:줄번호:컬럼:메시지코드: 설명 (코드명) 입니다.

📋 메시지 유형과 코드 이해하기

Pylint 메시지는 알파벳 접두사로 심각도를 구분합니다.

자주 마주치는 메시지 코드

⚙️ .pylintrc 설정 파일

프로젝트 루트에 .pylintrc 파일을 두면 팀 전체에 일관된 규칙을 적용할 수 있습니다.

기본 템플릿 생성

1

pylint --generate-rcfile > .pylintrc

주요 설정 항목

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

[MASTER]
# 가상환경, 외부 라이브러리 경로 추가
init-hook='import sys; sys.path.insert(0, "src")'

# 병렬 처리 (0 = CPU 수에 맞게 자동)
jobs=0

[MESSAGES CONTROL]
# 비활성화할 메시지 코드 (쉼표로 구분)
disable=
    C0114,  # missing-module-docstring
    C0115,  # missing-class-docstring
    C0116,  # missing-function-docstring
    W1203   # logging-fstring

[FORMAT]
# 한 줄 최대 길이 (PEP 8 기본값 79, 실무 100~120 권장)
max-line-length=120

# 들여쓰기 단위
indent-string='    '

[DESIGN]
# 함수 최대 인자 수
max-args=7

# 함수 최대 줄 수
max-statements=50

[TYPECHECK]
# 외부 라이브러리 타입 체크 오류 무시
ignored-modules=numpy,pandas,pydantic

🔕 경고 비활성화 방법

프로젝트 전체가 아닌 특정 코드에만 규칙을 비활성화할 때 인라인 주석을 사용합니다.

1줄 비활성화

1

import os  # pylint: disable=unused-import

블록 단위 비활성화

1
2
3
4

# pylint: disable=too-many-arguments
def complex_function(a, b, c, d, e, f):
    pass
# pylint: enable=too-many-arguments

파일 전체 비활성화

파일 최상단에 추가합니다.

1

# pylint: disable=missing-module-docstring,missing-function-docstring

⚠️ 인라인 비활성화를 남용하면 Pylint의 효과가 떨어집니다. 실제로 불필요한 경고만 선택적으로 끄고, 가능하면 .pylintrc에서 프로젝트 전체 기준을 설정하는 것이 바람직합니다.

🖥️ VSCode 연동

settings.json 설정

.vscode/settings.json에 다음을 추가합니다.

1
2
3
4
5
6
7
8

{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.linting.pylintArgs": [
    "--disable", "C0301",
    "--max-line-length", "120"
  ]
}

저장 시 자동 검사

1
2
3
4

{
  "editor.formatOnSave": true,
  "python.linting.lintOnSave": true
}

Tip: VSCode의 Python 확장(ms-python.python)을 설치하면 편집 중 실시간으로 Pylint 오류가 표시됩니다.

🔗 pre-commit으로 CI/CD 통합

커밋 시점에 Pylint를 자동 실행하면, 오류가 있는 코드는 커밋 자체가 차단됩니다.

pre-commit 설치

1

pip install pre-commit

.pre-commit-config.yaml 작성

1
2
3
4
5
6
7
8
9
10
11
12

repos:
  - repo: https://github.com/pycqa/pylint
    rev: v3.3.0
    hooks:
      - id: pylint
        args:
          - "--max-line-length=120"
          - "--disable=C0114,C0115,C0116"
        additional_dependencies:
          - pydantic
          - pyyaml
          - requests

훅 설치 및 실행

1
2
3
4
5

# 훅 설치 (최초 1회)
pre-commit install

# 전체 파일 수동 실행
pre-commit run --all-files

이후 git commit 시 자동으로 Pylint가 실행되며, 오류가 있으면 커밋이 차단됩니다.

GitHub Actions 통합

1
2
3
4
5
6
7
8
9
10
11
12
13
14

name: Lint

on: [push, pull_request]

jobs:
  pylint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install pylint
      - run: pylint src/ --fail-under=8.0

--fail-under=8.0 옵션으로 품질 점수가 8점 미만이면 CI가 실패합니다.

💡 실무 적용 팁

점진적 도입 전략

기존 프로젝트에 Pylint를 도입할 때는 처음부터 모든 규칙을 강제하면 수백 개의 오류가 나올 수 있습니다. 아래 순서로 단계적으로 접근하는 것을 권장합니다.

1. E(Error) 먼저 — 런타임 오류로 이어지는 치명적 문제 우선 해결
2. W(Warning) 다음 — 잠재적 버그와 개선 권장 사항 처리
3. C/R 마지막 — 코딩 규칙과 리팩토링은 여유를 두고 개선

자주 발생하는 오류 해결

Pyreverse로 UML 다이어그램 생성

Pylint 패키지에 포함된 pyreverse로 클래스 구조를 시각화할 수 있습니다. Graphviz 설치 후 실행합니다.

1
2
3
4

pip install pylint
brew install graphviz  # macOS

pyreverse -o png -p MyProject my_package/

classes_MyProject.png와 packages_MyProject.png 파일이 생성됩니다.

❓ 자주 묻는 질문

Q. Pylint와 Flake8 중 무엇을 써야 하나요?

간단한 스타일 검사가 목적이라면 Flake8이 빠르고 설정이 쉽습니다. 잠재적 버그 탐지, 코드 복잡도 분석, 품질 점수까지 필요하다면 Pylint가 적합합니다. 실무에서는 두 도구를 함께 사용하거나, 최근에는 Ruff로 통합하는 경우가 많습니다.

Q. Pylint 점수 10점을 목표로 해야 하나요?

아닙니다. 10점이 항상 좋은 코드를 의미하지는 않습니다. 팀의 기준(예: 8.0 이상)을 설정하고, 점수보다는 E·W 오류 0건을 목표로 삼는 것이 더 실용적입니다.

Q. 외부 라이브러리(numpy, pandas) 사용 시 E0401 오류가 계속 나옵니다.

.pylintrc의 [TYPECHECK] 섹션에 해당 라이브러리를 추가합니다.

1
2

[TYPECHECK]
ignored-modules=numpy,pandas,torch,tensorflow

Q. pre-commit 사용 시 가상환경 패키지를 인식하지 못합니다.

.pre-commit-config.yaml의 additional_dependencies에 프로젝트에서 사용하는 패키지를 명시해야 합니다.

1
2
3
4

additional_dependencies:
  - pydantic
  - sqlalchemy
  - fastapi