지윤이 차트 제목을 한국어로 바꿨다. "붓꽃 종류별 꽃받침 크기". 그런데 브라우저에 뜬 차트를 보니 제목 자리에 네모 박스들이 가득했다.

"선배, 한글이 다 깨져요."

"아, 그거. Plotly 기본 폰트가 한글을 지원 안 해. 한글 폰트 따로 지정해야 해."

Matplotlib도 처음에 똑같은 문제를 겪었었다. 데이터 시각화 라이브러리들의 공통 통과 의례 같은 문제였다.

왜 한글이 깨지나

Plotly의 기본 폰트는 "Open Sans"입니다. 이 폰트는 영문과 숫자를 지원하지만 한글 글리프를 포함하지 않습니다. 한글 문자를 만나면 대체 문자(네모)로 렌더링합니다.

해결 방법은 한글을 지원하는 폰트를 명시적으로 지정하는 것입니다.

OS별 한글 폰트

각 운영체제에 기본으로 설치된 한글 폰트가 있습니다.

단일 차트에 폰트 설정

update_layout(font=dict(family="..."))으로 특정 차트에만 폰트를 지정합니다.

# 파일: korean_font_basic.pyimport plotly.express as pximport platformdf = px.data.iris()# OS에 맞는 한글 폰트 선택system = platform.system()if system == "Windows":    korean_font = "Malgun Gothic"elif system == "Darwin":    # macOS    korean_font = "AppleGothic"else:                       # Linux    korean_font = "NanumGothic"fig = px.scatter(    df,    x="sepal_width",    y="sepal_length",    color="species",    labels={        "sepal_width": "꽃받침 너비 (cm)",        "sepal_length": "꽃받침 길이 (cm)",        "species": "종"    },    title="붓꽃 종류별 꽃받침 크기")fig.update_layout(    font=dict(family=korean_font, size=13))fig.show()

이제 한글이 정상적으로 표시됩니다.

전역 폰트 설정

매번 update_layout()을 호출하는 것이 번거롭다면, Plotly의 전역 템플릿을 수정하여 한 번만 설정할 수 있습니다.

# 파일: korean_font_global.pyimport plotly.express as pximport plotly.io as pioimport platform# OS 감지 후 폰트 설정system = platform.system()if system == "Windows":    korean_font = "Malgun Gothic"elif system == "Darwin":    korean_font = "AppleGothic"else:    korean_font = "NanumGothic"# 전역 폰트 설정pio.templates["plotly"].layout.font = dict(family=korean_font, size=13)pio.templates.default = "plotly"# 이후의 모든 차트에 자동 적용df = px.data.iris()fig1 = px.scatter(    df,    x="sepal_width",    y="sepal_length",    color="species",    title="붓꽃 산점도")fig1.show()fig2 = px.histogram(    df,    x="sepal_length",    color="species",    title="꽃받침 길이 분포")fig2.show()

pio.templates.default로 기본 템플릿을 지정하면, 이후 생성되는 모든 Figure에 해당 템플릿의 폰트 설정이 적용됩니다.

프로젝트 초기화 함수로 만들기

여러 파일에서 공통으로 사용한다면 초기화 함수를 하나 만들어 두는 것이 편합니다.

# 파일: plotly_setup.pyimport plotly.io as pioimport platformdef setup_plotly_korean():    """Plotly 한글 폰트 전역 설정."""    system = platform.system()    if system == "Windows":        font = "Malgun Gothic"    elif system == "Darwin":        font = "AppleGothic"    else:        font = "NanumGothic"    pio.templates["plotly"].layout.font = dict(family=font, size=13)    pio.templates.default = "plotly"    return font# 사용 예시if __name__ == "__main__":    import plotly.express as px    setup_plotly_korean()    df = px.data.tips()    fig = px.box(        df,        x="day",        y="total_bill",        color="sex",        title="요일별 식사 금액"    )    fig.show()

캡스톤 프로젝트에서 한 번만 setup_plotly_korean()을 호출해두면, 이후 모든 차트에서 한글이 정상 표시됩니다.

"이걸 프로젝트 시작할 때 한 번만 불러두면 되는 거네요."

"맞아. 설정 파일 하나 만들어서 import하면 끝이야."

자주 묻는 질문

Q: macOS에서 "AppleGothic" 대신 다른 폰트를 쓸 수 있나요?

"Apple SD Gothic Neo"도 사용할 수 있습니다. 더 현대적인 글꼴이지만, 일부 Python 환경에서 인식되지 않는 경우가 있으니 "AppleGothic"이 더 안정적입니다. "Nanum Gothic"을 별도로 설치해서 사용할 수도 있습니다.

Q: Linux에서 NanumGothic을 설치하려면 어떻게 하나요?

Ubuntu 기준으로 sudo apt-get install fonts-nanum으로 설치합니다. 설치 후 Python 환경을 재시작해야 적용됩니다.

Q: 웹 폰트(Google Fonts)를 사용할 수 있나요?

Plotly는 웹 폰트를 직접 지원하지 않습니다. 로컬 환경에 설치된 폰트만 사용할 수 있습니다. HTML로 내보내서 직접 CSS를 수정하는 방법은 있지만, 교재 범위를 넘어서는 내용입니다.