Gradio Favicon: Add a Custom Browser Icon the Right Way
If the browser tab shows a generic globe while your Gradio app loads normally, the app is missing its icon metadata. A Gradio favicon is easiest to add through the launcher, where Gradio can register the file without you editing its generated page template.
You do not need to place a <link> tag inside a gr.HTML component or duplicate the icon across every component. Configure the icon once at application startup, then confirm that the browser actually requests the file.
Prerequisites
Before you start, you need a Gradio application you can restart, one square icon file, and access to the process that starts the app.
A Gradio project with an app.py file or another Python entry point.
A square .ico file. For a predictable browser fallback, include 16 px, 32 px, and 48 px artwork in the container.
Access to your launch command or hosting platform, including permission to read the icon file.
If your artwork starts as PNG or SVG, convert it before deployment. You can use Mzu favicondl to create the ICO, then keep the generated file named favicon.ico. The PNG to ICO guide explains the sizing options.
1. Prepare the favicon file
Create an assets directory beside the Python entry point. Store the icon at a stable path so every copy of the project—local, container, or hosted—uses the same reference.
Design for the tab, not for a full logo page. A bold shape or one letter usually survives the 16-pixel rendering better than fine text. Keep the source square, and avoid relying on a wide image being cropped unpredictably.
2. Set the Gradio favicon with launch()
Pass the absolute file path to the favicon_path argument on demo.launch(). This is the Gradio-specific switch; do not put it inside 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))
The Path(__file__).resolve().parent expression anchors the icon to the script rather than the shell's current directory. The is_file() check catches a missing or mistyped asset before startup continues. Point this option to a local file; a remote image URL is not a substitute for a deployable asset.
3. Verify the icon locally
Stop the running server and start it again after changing code. Browser tabs cache icons aggressively, so verify the result in a new tab or a private window rather than relying on the old tab.
Inspect the page source under <head> and look for a link whose rel value is icon. The HTML specification defines icon as a link relation for an external resource, which lets the browser fetch that file separately from the app page.
In developer tools, open the Network panel and reload the page. Confirm that the icon request returns 200 rather than 404, and check that the response is the file you uploaded. If the link exists but the tab still shows an old symbol, use the broader favicon troubleshooting checklist to inspect caching and conflicting icon links.
4. Deploy the asset with the app
Deploy the icon with the application, not only on your laptop. Your delivery package needs both app.py and assets/favicon.ico at the relative locations shown above.
For a container image, copy the assets directory into the same stage or final image that contains app.py.
For Git-based deployment, commit the .ico file unless your hosting policy stores binary assets elsewhere.
For a custom server, ensure the startup command executes the script's demo.launch(...) call; a file in the repository cannot configure a running server by itself.
The same check matters when a platform supplies its own site-icon setting. If the Gradio app is embedded inside another page, the top-level document may control the browser tab. In that arrangement, update the parent page's icon as well as Gradio's launcher.
Common pitfalls
Most failed Gradio favicon setups come from a few small mistakes:
Wrong argument location:favicon_path belongs to launch(), not Blocks() or Interface().
Fragile relative path:assets/favicon.ico depends on where the process starts. Anchor it to __file__ as shown.
Missing deployment file: A successful local run does not prove the hosted build contains the .ico file.
Incorrect file contents: Do not rename a PNG file to favicon.ico; convert the artwork into the ICO format instead.
Stale browser cache: Open a fresh tab or clear the site's favicon data before changing application code again.
Parent-page conflict: If Gradio sits in an iframe, the outer page can still determine the tab icon.
Conclusion
A Gradio favicon is easiest to manage as a launch-time asset: put a square ICO beside the app, pass its resolved path to launch(favicon_path=...), and verify the rendered icon request. That keeps the implementation small and gives local and hosted Gradio apps one obvious file to update when the mark changes.
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))
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))
브라우저 탭에 일반적인 지구 아이콘이 표시되는 반면 Gradio 앱은 정상적으로 실행된다면, 앱에 아이콘 메타데이터가 설정되지 않은 것입니다. Gradio favicon은 launcher를 통해 추가하는 것이 가장 간단합니다. 이렇게 하면 Gradio가 생성된 페이지 템플릿을 직접 수정하지 않고도 파일을 등록할 수 있습니다.
<link> 태그를 gr.HTML 컴포넌트 안에 넣거나, 모든 컴포넌트에 아이콘을 중복 적용할 필요는 없습니다. 애플리케이션 시작 시 아이콘을 한 번 설정한 다음, 브라우저가 실제로 해당 파일을 요청하는지 확인하세요.
사전 준비
시작하기 전에 다음이 준비되어 있어야 합니다. 재시작할 수 있는 Gradio 애플리케이션, 정사각형 아이콘 파일 하나, 그리고 앱을 시작하는 프로세스에 대한 접근 권한입니다.
app.py 파일 또는 다른 Python entry point가 있는 Gradio 프로젝트.
전체 로고 페이지가 아니라 브라우저 탭을 염두에 두고 디자인하세요. 굵은 도형이나 글자 하나는 세밀한 텍스트보다 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가 모두 필요합니다.
container image를 사용하는 경우, app.py가 들어 있는 동일한 stage 또는 final image에 assets 디렉터리를 복사하세요.
Git 기반 deployment에서는 hosting policy가 binary asset을 다른 위치에 보관하는 경우를 제외하고 .ico 파일을 commit하세요.
custom server를 사용하는 경우, startup command가 script의 demo.launch(...) call을 실행하도록 보장하세요. repository에 있는 파일만으로 실행 중인 서버를 구성할 수는 없습니다.
플랫폼에서 별도의 site-icon 설정 기능을 제공하는 경우에도 같은 확인이 필요합니다. Gradio 앱이 다른 페이지 안에 삽입되어 있다면 최상위 document가 browser tab 아이콘을 결정할 수 있습니다. 이런 구성에서는 parent page의 아이콘과 Gradio의 launcher를 모두 업데이트해야 합니다.
흔한 실수
Gradio favicon 설정이 실패하는 대부분은 다음과 같은 작은 실수에서 발생합니다.
인수 위치 오류:favicon_path는 launch()에 지정해야 하며, Blocks()나 Interface()에 넣는 것이 아닙니다.
불안정한 상대 경로:assets/favicon.ico는 process가 시작되는 위치에 따라 달라집니다. 예시처럼 __file__을 기준으로 경로를 고정해야 합니다.
배포 파일 누락: 로컬에서 정상적으로 실행되었다고 해서 hosted build에 .ico 파일이 포함되어 있다는 뜻은 아닙니다.
잘못된 파일 내용: PNG 파일의 이름만 favicon.ico로 변경하지 마세요. 원본 이미지를 ICO format으로 변환해야 합니다.
오래된 browser cache: 애플리케이션 코드를 다시 변경하기 전에 새 탭을 열거나 사이트의 favicon 데이터를 삭제하세요.
Parent page와의 충돌: Gradio가 iframe 안에 배치되어 있으면 외부 페이지가 여전히 tab 아이콘을 결정할 수 있습니다.
결론
Gradio favicon은 launch 시점에 제공되는 asset으로 관리하는 것이 가장 간단합니다. 앱 옆에 정사각형 ICO 파일을 놓고, 경로를 resolve한 값을 launch(favicon_path=...)에 전달한 다음, 실제로 렌더링되는 아이콘 요청을 확인하면 됩니다. 이렇게 하면 구현이 단순하게 유지되며 로컬과 hosted Gradio 앱 모두에서 로고가 변경될 때 업데이트할 파일이 하나로 명확해집니다.
Si la pestaña del navegador muestra un globo genérico mientras tu app de Gradio carga con normalidad, significa que a la app le faltan los metadatos del icono. La forma más sencilla de añadir un favicon a Gradio es hacerlo desde el launcher, donde Gradio puede registrar el archivo sin que tengas que editar la plantilla de página que genera.
No necesitas insertar una etiqueta <link> dentro de un componente gr.HTML ni duplicar el icono en cada componente. Configúralo una sola vez al iniciar la aplicación y luego comprueba que el navegador solicite realmente el archivo.
Requisitos previos
Antes de empezar, necesitas una aplicación de Gradio que puedas reiniciar, un archivo de icono cuadrado y acceso al proceso que inicia la app.
Un proyecto de Gradio con un archivo app.py u otro punto de entrada de Python.
Un archivo .ico cuadrado. Para obtener un fallback predecible en el navegador, incluye diseños de 16 px, 32 px y 48 px en el contenedor.
Acceso al comando de launch o a la plataforma de hosting, incluido el permiso para leer el archivo del icono.
Si tu diseño empieza como PNG o SVG, conviértelo antes del despliegue. Puedes usar Mzu favicondl para crear el ICO y, después, conserva el archivo generado con el nombre favicon.ico. La guía para convertir PNG a ICO explica las opciones de tamaño.
1. Prepara el archivo favicon
Crea un directorio assets junto al punto de entrada de Python. Guarda el icono en una ruta estable para que todas las copias del proyecto —local, en un contenedor o alojadas— usen la misma referencia.
Diseña para la pestaña, no para una página de logotipo completa. Una forma audaz o una sola letra suelen conservar mejor su legibilidad en el renderizado de 16 píxeles que un texto con muchos detalles. Mantén el original cuadrado y no dependas de que una imagen ancha se recorte de forma impredecible.
2. Configura el favicon de Gradio con launch()
Pasa la ruta absoluta del archivo al argumento favicon_path de demo.launch(). Esta es la opción específica de Gradio; no la coloques dentro de 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))
La expresión Path(__file__).resolve().parent ancla el icono al script, no al directorio de trabajo actual de la shell. La comprobación is_file() detecta un asset ausente o una ruta mal escrita antes de que la aplicación siga arrancando. Configura esta opción con un archivo local; una URL de imagen remota no sustituye a un asset que pueda incluirse en el despliegue.
3. Verifica el icono localmente
Detén el servidor en ejecución y vuelve a iniciarlo después de cambiar el código. Las pestañas del navegador almacenan los iconos en caché de forma agresiva, así que verifica el resultado en una pestaña nueva o una ventana privada, en lugar de confiar en la pestaña anterior.
Inspecciona el código fuente de la página dentro de <head> y busca un enlace cuyo valor de rel sea icon. La especificación de HTML define icon como una relación de enlace para un recurso externo, lo que permite que el navegador solicite ese archivo por separado de la página de la app.
En las herramientas de desarrollo, abre el panel Network y recarga la página. Comprueba que la solicitud del icono devuelve 200 en lugar de 404 y que la respuesta corresponde al archivo que has subido. Si el enlace existe pero la pestaña todavía muestra el símbolo anterior, consulta la lista completa de troubleshooting de favicon para revisar la caché y los enlaces de iconos conflictivos.
4. Despliega el asset junto con la app
Despliega el icono junto con la aplicación, no solo en tu equipo. El paquete de entrega debe incluir tanto app.py como assets/favicon.ico en las ubicaciones relativas que se muestran arriba.
Para una imagen de contenedor, copia el directorio assets en el stage o la imagen final que contenga app.py.
Para despliegues basados en Git, haz commit del archivo .ico, salvo que la política de tu hosting guarde los assets binarios en otra ubicación.
Para un servidor personalizado, asegúrate de que el comando de inicio ejecute la llamada demo.launch(...) del script; un archivo en el repositorio no puede configurar por sí solo un servidor en ejecución.
La misma comprobación es importante cuando una plataforma ofrece su propia opción para configurar el icono del sitio. Si la app Gradio está incrustada en otra página, el documento principal puede controlar la pestaña del navegador. En ese caso, actualiza también el icono de la página contenedora, además del launcher de Gradio.
Problemas comunes
La mayoría de los intentos fallidos al configurar un favicon en Gradio se deben a algunos errores pequeños:
Ubicación incorrecta del argumento:favicon_path pertenece a launch(), no a Blocks() ni a Interface().
Ruta relativa frágil:assets/favicon.ico depende del directorio desde el que se inicia el proceso. Anclala a __file__ como se muestra.
Archivo de deployment ausente: Que la app funcione correctamente en local no demuestra que el build alojado incluya el archivo .ico.
Contenido incorrecto del archivo: No renombres un archivo PNG como favicon.ico; convierte la imagen al formato ICO.
Caché del navegador obsoleta: Abre una pestaña nueva o borra los datos del favicon del sitio antes de volver a modificar el código de la aplicación.
Conflicto con la página contenedora: Si Gradio está dentro de un iframe, la página exterior todavía puede determinar el icono de la pestaña.
Conclusión
Un favicon de Gradio es más fácil de gestionar como un recurso disponible en el momento del launch: coloca un archivo ICO cuadrado junto a la app, pasa su ruta resuelta a launch(favicon_path=...) y verifica la solicitud del icono renderizado. Así, la implementación se mantiene sencilla y las apps Gradio, tanto locales como alojadas, tienen un único archivo evidente que actualizar cuando cambie la marca.
Create a Gradio-ready favicon package
Convert a PNG or SVG into an ICO file, then deploy it with your Gradio app.