브라우저 탭에 일반적인 지구 아이콘이 표시되는 반면 Gradio 앱은 정상적으로 실행된다면, 앱에 아이콘 메타데이터가 설정되지 않은 것입니다. Gradio favicon은 launcher를 통해 추가하는 것이 가장 간단합니다. 이렇게 하면 Gradio가 생성된 페이지 템플릿을 직접 수정하지 않고도 파일을 등록할 수 있습니다.

<link> 태그를 gr.HTML 컴포넌트 안에 넣거나, 모든 컴포넌트에 아이콘을 중복 적용할 필요는 없습니다. 애플리케이션 시작 시 아이콘을 한 번 설정한 다음, 브라우저가 실제로 해당 파일을 요청하는지 확인하세요.

사전 준비

시작하기 전에 다음이 준비되어 있어야 합니다. 재시작할 수 있는 Gradio 애플리케이션, 정사각형 아이콘 파일 하나, 그리고 앱을 시작하는 프로세스에 대한 접근 권한입니다.

원본 artwork가 PNG 또는 SVG라면 배포 전에 변환하세요. Mzu favicondl을 사용해 ICO를 만들 수 있으며, 생성된 파일 이름은 favicon.ico로 유지하세요. PNG to ICO guide에서 sizing options에 대해 설명합니다.

1. favicon 파일 준비

Python entry point 옆에 assets 디렉터리를 만드세요. 프로젝트의 모든 복사본—로컬, container, hosted 환경—에서 동일한 reference를 사용할 수 있도록 아이콘을 안정적인 경로에 저장하세요.

your-gradio-app/
├── app.py
└── assets/
    └── favicon.ico

전체 로고 페이지가 아니라 브라우저 탭을 염두에 두고 디자인하세요. 굵은 도형이나 글자 하나는 세밀한 텍스트보다 16-pixel 크기로 렌더링될 때 대체로 더 잘 유지됩니다. 원본은 정사각형으로 유지하고, 폭이 넓은 이미지가 예측할 수 없는 위치에서 잘리는 방식에 의존하지 마세요.

2. launch()로 Gradio favicon 설정

demo.launch()의 favicon_path 인자에 절대 파일 경로를 전달하세요. 이는 Gradio 전용 설정이며, gr.Blocks() 안에 넣으면 안 됩니다.

from pathlib import Path

import gradio as gr

app_dir = Path(__file__).resolve().parent
favicon = app_dir / 'assets' / 'favicon.ico'

if not favicon.is_file():
    raise FileNotFoundError(f'Favicon not found: {favicon}')

with gr.Blocks() as demo:
    gr.Markdown('# My Gradio app')

demo.launch(favicon_path=str(favicon))

Path(__file__).resolve().parent 표현식은 아이콘의 기준 경로를 셸의 현재 디렉터리가 아니라 스크립트로 고정합니다. is_file() 검사는 시작이 계속 진행되기 전에 누락되었거나 경로가 잘못 입력된 asset을 감지합니다. 이 옵션은 로컬 파일을 가리키도록 지정하세요. 원격 이미지 URL은 배포 가능한 asset을 대신할 수 없습니다.

3. 로컬에서 아이콘 확인

코드를 변경한 뒤 실행 중인 서버를 중지하고 다시 시작하세요. 브라우저 탭은 아이콘을 강하게 캐시하므로 기존 탭만 믿지 말고 새 탭이나 시크릿 창에서 결과를 확인하세요.

페이지 소스에서 <head> 영역을 확인하고 rel 값이 icon인 link를 찾으세요. HTML 명세는 icon을 외부 resource를 위한 link relation으로 정의합니다. 이를 통해 브라우저는 애플리케이션 페이지와 별개로 해당 파일을 가져올 수 있습니다.

개발자 도구에서 Network 패널을 열고 페이지를 새로고침하세요. icon 요청이 404가 아니라 200을 반환하는지 확인하고, 응답이 업로드한 파일과 일치하는지도 확인하세요. link가 존재하는데도 탭에 기존 아이콘이 계속 보인다면, 더 포괄적인 favicon 문제 해결 체크리스트를 사용해 캐시와 서로 충돌하는 icon link를 점검하세요.

4. 애플리케이션과 함께 favicon 배포

favicon을 애플리케이션과 함께 배포해야 합니다. 노트북에만 두는 것으로는 부족합니다. 배포 패키지에는 위에서 표시한 상대 경로 위치에 app.py와 assets/favicon.ico가 모두 필요합니다.

플랫폼에서 별도의 site-icon 설정 기능을 제공하는 경우에도 같은 확인이 필요합니다. Gradio 앱이 다른 페이지 안에 삽입되어 있다면 최상위 document가 browser tab 아이콘을 결정할 수 있습니다. 이런 구성에서는 parent page의 아이콘과 Gradio의 launcher를 모두 업데이트해야 합니다.

흔한 실수

Gradio favicon 설정이 실패하는 대부분은 다음과 같은 작은 실수에서 발생합니다.

결론

Gradio favicon은 launch 시점에 제공되는 asset으로 관리하는 것이 가장 간단합니다. 앱 옆에 정사각형 ICO 파일을 놓고, 경로를 resolve한 값을 launch(favicon_path=...)에 전달한 다음, 실제로 렌더링되는 아이콘 요청을 확인하면 됩니다. 이렇게 하면 구현이 단순하게 유지되며 로컬과 hosted Gradio 앱 모두에서 로고가 변경될 때 업데이트할 파일이 하나로 명확해집니다.