Matplotlib으로 그래프를 그릴 때 한글 레이블이 네모 박스(□□□)로 깨지거나, 음수 부호가 제대로 표시되지 않는 문제를 경험한 적이 있을 것입니다. 이는 Matplotlib의 기본 폰트가 한글을 지원하지 않기 때문이며, OS별로 폰트 설정과 캐시 처리 방식이 달라 해결 방법도 다릅니다. 이 글에서는 Windows, Linux, Mac 환경에서 한글 폰트 깨짐을 완벽하게 해결하는 방법을 단계별로 제시합니다.
 |
| Python Matplotlib 한글 폰트 깨짐 완벽 해결 가이드 Windows Linux Mac |
1. 문제 원인 진단: 왜 한글이 깨지는가?
Matplotlib은 기본적으로 DejaVu Sans 폰트를 사용하며, 이 폰트는 한글 글리프(Glyph)를 포함하지 않습니다. 따라서 한글을 렌더링할 수 없어 대체 문자(□)로 표시됩니다. 추가로 axes.unicode_minus 옵션이 True로 설정되어 있으면, 유니코드 마이너스 기호(U+2212)를 사용하려 하지만 폰트가 이를 지원하지 않으면 깨져 보입니다.
- 한글 깨짐: 한글 글리프가 없는 폰트를 사용 중
- 마이너스 기호 깨짐: axes.unicode_minus=True 상태에서 폰트가 유니코드 마이너스를 미지원
- 캐시 문제: 폰트를 설치했어도 Matplotlib 캐시가 갱신되지 않아 반영 안 됨
해결의 핵심은 한글을 지원하는 폰트를 설치하고, Matplotlib 설정에 명시적으로 등록한 뒤, 캐시를 갱신하는 것입니다.
2. 빠른 해결: rcParams로 폰트 즉시 적용
코드 상단에 다음 설정을 추가하면 세션 내에서 즉시 한글 폰트를 적용할 수 있습니다. 이 방법은 임시 해결책으로, 매번 코드를 실행할 때마다 설정해야 합니다.
import matplotlib as mpl
import matplotlib.pyplot as plt
# 한글 폰트 설정 (Windows: 굴림, Mac: AppleGothic, Linux: NanumGothic)
plt.rcParams['font.family'] = 'gulim' # OS에 맞게 변경
plt.rcParams['axes.unicode_minus'] = False # 마이너스 기호 깨짐 방지
# 테스트 그래프
x = [1, 2, 3, 4, 5]
y = [-2, 4, -6, 8, -10]
plt.plot(x, y)
plt.title('한글 제목 테스트')
plt.xlabel('X축')
plt.ylabel('Y축')
plt.show()
- Windows: 'gulim', 'malgun gothic', 'nanumgothic' 등 사용 가능
- Mac: 'AppleGothic', 'AppleMyungjo' 권장
- Linux: 나눔폰트 설치 후 'NanumGothic' 사용 (설치:
sudo apt install fonts-nanum)
주의: 폰트명은 대소문자를 구분하지 않지만, 시스템에 실제 설치된 폰트명과 정확히 일치해야 합니다. 폰트 목록 확인은 다음 코드로 가능합니다.
import matplotlib.font_manager as fm fonts = [f.name for f in fm.fontManager.ttflist] print(sorted(set(fonts)))
3. 영구 해결: matplotlibrc 설정 파일 수정
매번 코드에 설정을 추가하는 것이 번거롭다면, matplotlibrc 설정 파일을 직접 수정하여 전역 기본값을 변경할 수 있습니다.
3-1. 설정 파일 위치 확인
import matplotlib as mpl print(mpl.matplotlib_fname())
출력된 경로의 파일을 텍스트 에디터로 열고 다음 항목을 수정합니다.
3-2. matplotlibrc 수정
# font.family 주석 해제 후 원하는 폰트로 변경 font.family: NanumGothic # 마이너스 기호 깨짐 방지 axes.unicode_minus: False
수정 후 저장하고 Jupyter Notebook이나 Python 인터프리터를 재시작해야 반영됩니다.
3-3. 폰트 캐시 삭제 (중요)
설정을 변경했는데도 한글이 깨진다면, Matplotlib 폰트 캐시가 문제일 가능성이 높습니다. 캐시 경로를 확인하고 fontlist 파일을 삭제하십시오.
import matplotlib as mpl print(mpl.get_cachedir())
출력된 경로로 이동하여 fontlist-v390.json (버전에 따라 숫자 다름) 파일을 삭제한 후, Python 환경을 재시작하면 캐시가 재구축됩니다.
- Windows:
C:\Users\사용자명\.matplotlib - Mac/Linux:
~/.matplotlib또는~/.cache/matplotlib
팁: 코드로 캐시를 재구축하려면 다음을 실행하십시오.
from matplotlib import font_manager font_manager._rebuild()
4. 고급 설정: 특정 폰트 파일 직접 등록
시스템에 설치된 폰트를 사용하지 않고, 프로젝트 내 폰트 파일(.ttf)을 직접 등록하여 이식성을 높일 수 있습니다. 이 방법은 Docker 컨테이너나 CI/CD 환경에서 유용합니다.
import matplotlib.pyplot as plt
import matplotlib.font_manager as fm
# 폰트 파일 경로 지정 (프로젝트 내 fonts/ 폴더에 배치)
font_path = './fonts/NanumGothic.ttf'
fm.fontManager.addfont(font_path)
# 폰트 이름 추출 후 전역 설정
font_name = fm.FontProperties(fname=font_path).get_name()
plt.rcParams['font.family'] = font_name
plt.rcParams['axes.unicode_minus'] = False
plt.title('프로젝트 내장 폰트 테스트')
plt.show()
Windows 폰트 설치 시 주의사항: .ttf 파일을 더블클릭하여 설치할 때, 반드시 '모든 사용자용으로 설치'를 선택해야 C:\Windows\Fonts에 설치됩니다. 현재 사용자만 설치하면 경로 문제로 Matplotlib이 폰트를 찾지 못할 수 있습니다.
특정 텍스트에만 다른 폰트 적용
제목은 볼드체, 레이블은 일반체로 구분하고 싶다면 FontProperties를 사용하십시오.
from matplotlib.font_manager import FontProperties
bold_font = FontProperties(fname='./fonts/NanumGothicBold.ttf')
plt.title('굵은 제목', fontproperties=bold_font)
plt.xlabel('일반 레이블') # 전역 설정 폰트 사용
5. OS별 권장 폰트 및 트러블슈팅
| OS | 권장 폰트 | 설치 명령어 | rcParams 설정값 |
|---|---|---|---|
| Windows | 맑은 고딕, 굴림, 나눔고딕 | 기본 설치됨 (나눔: 수동 다운로드) | 'malgun gothic', 'gulim' |
| Mac | AppleGothic, AppleMyungjo | 기본 설치됨 | 'AppleGothic' |
| Linux (Ubuntu) | 나눔고딕, 본고딕 | sudo apt install fonts-nanum | 'NanumGothic' |
자주 발생하는 문제와 해결
- 폰트를 설치했는데도 깨짐: 캐시 삭제 후 Python 재시작 필수
- Jupyter Notebook에서만 안 됨: Jupyter 커널 재시작 (
Kernel > Restart) - Linux에서 fc-list로 폰트 확인:
fc-list :lang=ko명령어로 한글 폰트 목록 확인 - Docker 환경: Dockerfile에
RUN apt-get install -y fonts-nanum추가 후 캐시 재구축
디버깅 팁: 다음 코드로 현재 적용된 폰트를 확인할 수 있습니다.
import matplotlib.pyplot as plt print(plt.rcParams['font.family']) print(plt.rcParams['axes.unicode_minus'])
정리 및 Action Item
Matplotlib 한글 깨짐은 폰트 설치 → rcParams 설정 → 캐시 삭제 3단계로 해결됩니다. 임시 해결은 plt.rcParams로, 영구 해결은 matplotlibrc 수정으로 처리하며, 캐시 문제가 가장 빈번하므로 반드시 fontlist 파일을 삭제하고 환경을 재시작하십시오.
당장 실행할 것: 위 2번 섹션의 코드를 복사하여 현재 작업 중인 Jupyter Notebook 최상단에 붙여넣고 실행하십시오. 한글이 정상 출력되면 3번 섹션으로 넘어가 영구 설정을 진행하면 됩니다.
#함께 읽으면 좋은 글
Python OpenAI API RateLimitError 및 토큰 초과 오류 완벽 해결 가이드 : 바로보기
댓글
댓글 쓰기