깔끔한 Streamlit 대시보드를 완성하고 팀에 링크를 공유했는데, 누군가 이렇게 물었습니다. “브라우저 탭에 우리 브랜드 대신 일반적인 Streamlit 로고가 표시되는 이유는 무엇인가요?” 해결책은 아마 건너뛴 매개변수 하나인 page_icon에 있습니다. 이 튜토리얼에서는 로컬 이미지, emoji, URL을 사용해 Streamlit favicon을 설정하고, 실제로 탭에 표시되는지 확인하는 방법을 단계별로 설명합니다.
page_icon이 실제로 제어하는 범위
Streamlit은 앱을 자동으로 생성한 페이지 안에서 렌더링합니다. st.set_page_config() 함수는 브라우저 탭에 어떤 아이콘을 사용할지, 그리고 일부 브라우저에서는 즐겨찾기에 어떤 아이콘을 사용할지를 지정하는 page_icon 인수를 받습니다. 이것이 완전한 HTML favicon 구성인 것은 아닙니다. 탭 아이콘을 설정하기 위한 Streamlit 자체의 훅입니다.
HTML 명세에 따르면 favicon은 문서의 head에 rel="icon" 링크를 추가해 선언합니다(WHATWG HTML spec). page_icon을 전달하면 Streamlit이 이 링크를 대신 처리합니다. favicon이란 무엇이며 어디에 표시되는지 자세히 알고 싶다면 favicon이란 무엇인가에 대한 가이드를 참고하세요.
사전 준비 사항
- 정상적으로 실행되는 Streamlit 앱이 필요합니다.
st.set_page_config를 지원하는 버전이어야 합니다. - 아이콘 파일이 필요합니다. 정사각형 PNG, JPG 또는 SVG를 사용하세요. 가장 좋은 결과를 위해 최소 64×64 px 크기의 정사각형 이미지를 사용하세요.
streamlit run app.py를 실행하는 기본적인 사용법만 알고 있으면 됩니다.
단계별 안내: Streamlit favicon 설정하기
1단계 — set_page_config를 가장 먼저 호출
st.set_page_config()는 스크립트에서 가장 먼저 실행되는 Streamlit 명령어여야 합니다. 그 전에 st.title()이나 다른 Streamlit 함수를 호출하면 Streamlit이 오류를 발생시킵니다. 앱 파일의 맨 위에 import 바로 다음에 배치하세요.
import streamlit as st
st.set_page_config(
page_title="My Dashboard",
page_icon="icon.png"
)
st.title("My Dashboard")
2단계 — page_icon에서 이미지 지정
page_icon에는 다음 값을 사용할 수 있습니다.
- 프로젝트 내 이미지 파일의 상대 경로입니다. 예를 들어
"icon.png"처럼 지정합니다. - 절대 경로입니다. 예를 들어
"/home/user/app/icon.png"처럼 지정합니다. - 이미지 URL입니다. 예를 들어
"https://example.com/icon.png"처럼 지정합니다. - 이모지 한 글자입니다. 예를 들어
"🚀"처럼 지정합니다.
브랜드 아이콘에는 로컬 PNG 또는 SVG를 사용하는 것이 가장 안정적입니다. 파일을 앱 스크립트와 같은 디렉터리에 두거나, streamlit run을 실행하는 위치를 기준으로 한 상대 경로를 사용하세요.
3단계 — 이미지가 아직 없다면 이모지 사용
프로토타이핑 중이라면 이모지를 사용하는 것이 가장 빠릅니다. Streamlit가 이를 탭 아이콘으로 변환합니다.
st.set_page_config(page_title="Prototype", page_icon="📊")
내부 도구에는 편리하지만 브랜드와는 일치하지 않습니다. 릴리스할 준비가 되면 실제 이미지 파일로 교체하세요.
4단계 — 적합한 아이콘 파일 준비
Streamlit는 일반적인 이미지 형식을 지원하지만, 여러 브라우저에서 가장 잘 맞는 것은 투명 배경의 정사각형 PNG입니다. 로고만 있다면 마크 부분만 잘라내고 64×64 또는 128×128 px 크기로 조정하세요. 이미지에서 favicon을 만드는 방법에 관한 가이드에서 자르기와 단순화 단계를 자세히 설명합니다.
다른 곳에서도 ICO 파일이 필요하다면 Mzu favicondl을 사용해 PNG를 변환할 수 있습니다. Streamlit 자체는 ICO를 요구하지 않지만, traditional favicon을 사용하는 custom domain에서 앱을 제공하는 경우에도 ICO 파일을 하나 준비해 두면 도움이 됩니다.
5단계 — 탭 아이콘 확인
앱을 실행한 뒤 브라우저에서 열고 탭을 확인하세요. 기본 Streamlit 아이콘이 계속 보인다면 강력 새로고침(Ctrl+Shift+R 또는 Cmd+Shift+R)을 실행하세요. 브라우저는 favicon을 강하게 캐시하므로 코드를 변경해도 기존 아이콘이 오래 남을 수 있습니다. 더 자세한 확인 항목은 favicon이 표시되지 않을 때를 참고하세요.
자주 발생하는 문제
- set_page_config 호출 시점이 너무 늦었습니다. 반드시 Streamlit에서 처음 호출하는 API여야 합니다. 코드를 맨 위로 옮기면 오류가 해결됩니다.
- 파일 경로가 잘못되었습니다. 상대 경로는 스크립트가 있는 폴더가 아니라 Streamlit을 실행한 디렉터리를 기준으로 해석됩니다. 경로가 확실하지 않다면 절대 경로를 사용하세요.
- 이미지가 정사각형이 아닙니다. 가로로 긴 로고는 정사각형 영역에 맞게 눌리거나 레터박스로 표시됩니다. 먼저 정사각형으로 crop하세요.
- 브라우저 캐시입니다. 탭에 이전 아이콘이 잠시 남아 있을 수 있습니다. 하드 새로고침을 하거나 private window에서 테스트하세요.
- 배포 환경마다 경로가 다릅니다. Streamlit Community Cloud나 container에서 실행하면 working directory가 로컬 환경과 다를 수 있습니다. 앱 파일을 기준으로 한 상대 경로 또는 배포 환경에 실제로 존재하는 절대 경로를 사용하세요.
page_icon만으로 부족한 경우
page_icon은 Streamlit 앱 자체의 브라우저 탭 아이콘을 설정합니다. 앱을 더 큰 사이트에 임베드하거나 Apple Touch icon과 web app manifest가 필요하다면, 이 항목들은 주변 HTML에서 별도로 처리해야 합니다. 완전한 icon stack을 구성하려면 favicon best practices를 참고하세요.
Streamlit favicon 설정은 아이콘을存放할 위치를 알고 나면 한 줄의 코드 변경으로 끝납니다. 스크립트 맨 위에서 st.set_page_config(page_title=..., page_icon=...)을 추가하고, 정사각형 PNG 또는 SVG를 사용한 다음 하드 새로고침으로 확인하세요. 이렇게만 설정하면 브라우저 탭의 기본 Streamlit 로고를 자체 브랜드 아이콘으로 바꿀 수 있습니다.