Matplotlib 에서 한글 폰트 깨짐 문제 해결하기 (Mac)

Matplotlib을 사용하여 시각화를 할 때, 한글 텍스트가 깨지거나 표시되지 않는 문제를 자주 겪게 됩니다.

이는 Matplotlib의 기본 폰트가 한글을 지원하지 않기 때문입니다. 이번 글에서는 Matplotlib에서 한글 폰트가 깨지는 문제를 해결하기 위한 구체적인 방법을 정리해보겠습니다.

1. 문제 상황

한글 텍스트가 포함된 그래프를 그리려고 하면 다음과 같은 오류가 발생하거나, 한글이 깨져 보이는 상황이 발생합니다:

UserWarning: Glyph ... missing from font(s)
한글이 사각형으로 표시되거나 빈 텍스트로 나옴
한글 텍스트가 제대로 렌더링되지 않음

이 문제는 Matplotlib에서 한글을 지원하는 폰트를 기본적으로 사용하지 않기 때문입니다.

아래 코드로 해결 할 수 있습니다.

    #한글폰트 처리
    plt.rcParams['font.family'] = 'AppleGothic' # 맥 기본 한글 서체
    plt.rcParams['axes.unicode_minus'] = False # 마이너스 기호 깨짐 방지

하지만! 저는 나눔고딕을 쓰고싶었습니다.

전날 챗지피티에게 제 가계부 월말결산 차트를 그려달라했을때도 글씨가 깨지는 문제가 있었거든요.

이것도 나눔고딕체였는데...

많이 쓰이는 폰트니 꼭 해결하고 싶었습니다.

우선 폰트가 제대로 깔린게 맞는지 확인합니다.

2. 해결 방법

2.1 폰트가 Matplotlib에 정상적으로 등록되었는지 확인

Matplotlib이 설치된 폰트를 인식하고 있는지 확인합니다.

Mac에서 폰트 확인 (Spotlight 사용)

커맨드(⌘) + 스페이스바를 눌러 Spotlight 검색창을 엽니다.
"Font Book"(서체 관리자)을 검색 후 실행합니다.
설치된 폰트 목록에서 NanumGothic 폰트가 있는지 확인합니다.

Python 코드로 확인

import matplotlib.font_manager as fm

# 현재 시스템에서 Matplotlib이 인식하는 모든 폰트 목록 확인
font_list = [f.name for f in fm.fontManager.ttflist]
print("설치된 폰트 목록:", font_list)

# 'NanumGothic'이 있는지 확인
if 'NanumGothic' in font_list:
    print("✅ 'NanumGothic' 폰트가 정상적으로 인식되었습니다!")
else:
    print("❌ 'NanumGothic' 폰트가 Matplotlib에서 인식되지 않습니다.")

출력 결과에 NanumGothic이 없다면?

Matplotlib이 NanumGothic 폰트를 감지하지 못한 것입니다.
다음 단계를 진행하여 폰트 캐시를 강제로 갱신해야 합니다.

# 폰트매니저에서는 나눔고딕이 잘 확인되지만, 출력결과는 ❌ 였습니다.

2.2 폰트 캐시 강제 갱신 (재생성)

Matplotlib이 폰트를 다시 스캔하도록 강제 갱신하려면 폰트 캐시를 삭제한 후 다시 생성해야 합니다.

🔹 Mac/Linux: 터미널에서 캐시 삭제

캐시파일 확인

ls -la ~/.matplotlib/

fontlist.json을 삭제합니다.

rm ~/.matplotlib/fontlist.json

rm ~/.matplotlib/fontlist-v390.json

fontlist-v390.json 파일이 존재하는 경우, fontList.json이 아니라 이 파일을 삭제하면 됩니다.

🔹 Windows: Python 코드로 삭제

import os

cache_path = os.path.join(os.path.expanduser("~"), ".matplotlib", "fontlist-v390.json")
if os.path.exists(cache_path):
    os.remove(cache_path)
    print("✅ 폰트 캐시 삭제 완료! Python을 재시작하세요.")

📌 중요한 점:
폰트 캐시를 삭제한 후 Python을 완전히 종료하고 다시 실행해야 적용됩니다.

2.3 폰트가 다시 감지되었는지 확인

폰트 캐시를 삭제한 후, Python을 다시 실행하고 아래 코드를 실행하여 폰트가 정상적으로 인식되었는지 확인합니다.

import matplotlib.font_manager as fm

# 폰트 목록을 다시 확인
font_list = [f.name for f in fm.fontManager.ttflist]
print("설치된 폰트 목록:", font_list)

# 'NanumGothic'이 인식되었는지 다시 확인
if 'NanumGothic' in font_list:
    print("✅ 'NanumGothic' 폰트가 정상적으로 인식되었습니다!")
else:
    print("❌ 'NanumGothic' 폰트가 Matplotlib에서 인식되지 않습니다.")

2.4 Matplotlib에 한글 폰트 적용

폰트가 정상적으로 감지되었다면, 이제 Matplotlib에 적용합니다.

2.4.1 폰트 설정 코드

설치된 한글 폰트를 Matplotlib에 적용하려면 다음 코드를 사용합니다.

import matplotlib.pyplot as plt
import matplotlib.font_manager as fm

# 나눔고딕 폰트 경로 설정 (Mac 예시)
font_path = "/Users/사용자이름/Library/Fonts/NanumGothic.ttf"
font_prop = fm.FontProperties(fname=font_path)

# Matplotlib 기본 설정
plt.rcParams['font.family'] = font_prop.get_name()
plt.rcParams['axes.unicode_minus'] = False  # 마이너스 기호 깨짐 방지

print("적용된 폰트:", font_prop.get_name())

2.4.2 한글 폰트 테스트

위 설정이 제대로 적용되었는지 확인하기 위해 다음 코드를 실행합니다:

plt.figure(figsize=(6, 4))
plt.text(0.5, 0.5, "한글 폰트 테스트: 나눔고딕", fontsize=20, ha='center')
plt.xticks([])
plt.yticks([])
plt.show()

한글 텍스트가 제대로 표시된다면 설정이 성공적으로 적용된 것입니다.

3. 참고: Matplotlib에서 폰트 목록 확인하기

Matplotlib이 시스템에서 인식하는 폰트 목록을 확인하려면 다음 코드를 실행하세요:

import matplotlib.font_manager as fm

font_list = [f.name for f in fm.fontManager.ttflist]
print("설치된 폰트 목록:", font_list)

여기에서 NanumGothic이 포함되어 있는지 확인할 수 있습니다.

4. Streamlit App에서의 한글깨짐 문제 해결하기

로컬에서는 해결완료... BUT... 스트림릿 앱에서는 또 한글이 깨집니다.

해당 문제는 스트림릿 앱에 폰트가 없어서 발생!

폰트를 설치해줍니다.

custom_fonts 폴더에 폰트를 함께 푸쉬하고, 글씨를 설치하는 코드 작성

import os
import matplotlib.font_manager as fm

@st.cache_data
def fontRegistered():
    font_dirs = [os.getcwd() + '/custom_fonts']
    font_files = fm.findSystemFonts(fontpaths=font_dirs)
    for font_file in font_files:
        fm.fontManager.addfont(font_file)
    fm._load_fontmanager(try_read_cache=False)



def main():

    fontRegistered()
    plt.rc('font', family='NanumGothic')

어째

폰트를 설치하고 다시 불러왔는데도 계속 글씨가 깨지는 문제 발생...

앱 재시작을 해도 여전히 글씨가 깨짐

fm._load_fontmanager(try_read_cache=False) 자체가 폰트 캐시메모리 다시불러오는 코드인데...

캐시메모리 전부 지우는 방법을 사용해봤습니다.

st.cache_data.clear()

@st.cache_data 데코레이터로 캐시된 모든 데이터를 지웁니다.

이 함수는 Streamlit 앱의 모든 인메모리 및 디스크 상의 데이터 캐시를 지웁니다

어제처럼 캐시를 지우고 다시 받아오면 될까 싶어서 추가했더니 해결되었습니다.

@st.cache_data
def fontRegistered():
# 전체 캐시지우기
    st.cache_data.clear()
    font_dirs = [os.getcwd() + '/custom_fonts']
    font_files = fm.findSystemFonts(fontpaths=font_dirs)
    for font_file in font_files:
        fm.fontManager.addfont(font_file)
    fm._load_fontmanager(try_read_cache=False)
## 한글폰트 설정

캐시를 매번 지울경우의 문제점

st.cache_data.clear()를 매번 실행하면 캐시의 이점을 잃게 됩니다.

폰트 등록 과정이 매번 새로 실행되어 앱의 시작 시간이 늘어날 수 있습니다.

한번 지웠더니 이후엔 깨지지 않길래 해당 코드를 삭제했습니다.

5. 결론

Matplotlib에서 한글 폰트 문제를 해결하기 위해 다음 단계를 따라야 합니다:

폰트가 Matplotlib에 정상적으로 등록되었는지 확인 (Spotlight로도 확인 가능)
폰트 캐시 강제 갱신
폰트가 다시 감지되었는지 확인
Matplotlib에 한글 폰트 적용

이 과정을 완료하면 Matplotlib에서 한글 텍스트를 문제없이 사용할 수 있습니다.

원하는 글씨체로도 설정 완료! 😊

매일코딩

Matplotlib 에서 한글 폰트 깨짐 문제 해결하기 (Mac)

1. 문제 상황

2. 해결 방법

2.1 폰트가 Matplotlib에 정상적으로 등록되었는지 확인

Mac에서 폰트 확인 (Spotlight 사용)

Python 코드로 확인

출력 결과에 NanumGothic이 없다면?

2.2 폰트 캐시 강제 갱신 (재생성)

🔹 Mac/Linux: 터미널에서 캐시 삭제

🔹 Windows: Python 코드로 삭제

2.3 폰트가 다시 감지되었는지 확인

2.4 Matplotlib에 한글 폰트 적용

2.4.1 폰트 설정 코드

2.4.2 한글 폰트 테스트

3. 참고: Matplotlib에서 폰트 목록 확인하기

4. Streamlit App에서의 한글깨짐 문제 해결하기

캐시를 매번 지울경우의 문제점

5. 결론

티스토리툴바

Matplotlib 에서 한글 폰트 깨짐 문제 해결하기 (Mac)

1. 문제 상황

2. 해결 방법

2.1 폰트가 Matplotlib에 정상적으로 등록되었는지 확인

Mac에서 폰트 확인 (Spotlight 사용)

Python 코드로 확인

출력 결과에 NanumGothic이 없다면?

2.2 폰트 캐시 강제 갱신 (재생성)

🔹 Mac/Linux: 터미널에서 캐시 삭제

🔹 Windows: Python 코드로 삭제

2.3 폰트가 다시 감지되었는지 확인

2.4 Matplotlib에 한글 폰트 적용

2.4.1 폰트 설정 코드

2.4.2 한글 폰트 테스트

3. 참고: Matplotlib에서 폰트 목록 확인하기

4. Streamlit App에서의 한글깨짐 문제 해결하기

캐시를 매번 지울경우의 문제점

5. 결론

관련글

티스토리툴바