Tienes una aplicación FastAPI en funcionamiento y la documentación de la API se ve muy bien, pero la pestaña del navegador sigue mostrando un cuadrado vacío o el icono predeterminado del globo. Es un problema habitual: FastAPI no sirve automáticamente un favicon y, a diferencia de Flask o Django, no incluye una convención integrada para él. La solución es sencilla cuando sabes dónde colocar el archivo y cómo exponerlo.
En esta guía te mostraremos los pasos exactos para servir un fastapi favicon usando StaticFiles, una ruta dedicada o una etiqueta de plantilla. También explicaremos el marcado HTML que hace que los navegadores detecten el icono de forma fiable, además de los errores que provocan 404 e iconos obsoletos.
Requisitos previos
Antes de empezar, asegúrate de tener:
- Un proyecto FastAPI que funcione (cualquier versión compatible con
StaticFiles, es decir, todas las versiones modernas). - Un archivo favicon listo. Puedes usar un ICO, PNG o SVG. Si necesitas crear uno, consulta nuestra guía de favicon en HTML o genera un ICO de varios tamaños con Mzu favicondl.
- Familiaridad básica con el enrutamiento de FastAPI y las plantillas Jinja2 (si sirves HTML).
Paso 1: Coloca el archivo favicon en un directorio estático
Crea una carpeta llamada static en la raíz de tu proyecto (o donde prefieras). Coloca dentro el archivo favicon. Para máxima compatibilidad, ponle el nombre favicon.ico y, si tienes una versión PNG o SVG, inclúyela también.
myproject/
├── main.py
├── static/
│ └── favicon.ico
└── templates/
└── index.htmlSi solo tienes un PNG, también funciona; basta con referenciarlo correctamente en el HTML. El formato ICO sigue siendo solicitado por los navegadores cuando no está presente una etiqueta link, por lo que tener /favicon.ico disponible evita un 404 en la consola.
Paso 2: Monta StaticFiles en tu aplicación FastAPI
FastAPI utiliza StaticFiles de Starlette para servir archivos estáticos. Añade lo siguiente a tu main.py:
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
app = FastAPI()
app.mount('/static', StaticFiles(directory='static'), name='static')Esto hace que cualquier archivo de static/ esté disponible en /static/filename. Por tanto, tu favicon estará en /static/favicon.ico.
Paso 3: Añade la etiqueta link en tu HTML
Si sirves plantillas HTML (usando Jinja2Templates), incluye el enlace al favicon dentro del <head> de tu plantilla base. El atributo rel debe tener el valor icon, según la especificación HTML.
<link rel='icon' type='image/x-icon' href='/static/favicon.ico'>Si también tienes un SVG o PNG, inclúyelos con los atributos type correspondientes. Los navegadores seleccionarán el formato mejor compatible. Para profundizar en el orden de los link tags, consulta nuestra guía sobre el link tag del favicon.
Paso 4: Sirve /favicon.ico directamente (opcional, pero recomendado)
Los navegadores y algunas herramientas siguen solicitando /favicon.ico en la raíz aunque tengas un link tag. Para evitar un 404, puedes añadir una ruta específica que devuelva el archivo:
from fastapi import FastAPI
from fastapi.responses import FileResponse
app = FastAPI()
@app.get('/favicon.ico', include_in_schema=False)
async def favicon():
return FileResponse('static/favicon.ico')El parámetro include_in_schema=False mantiene la ruta fuera de la documentación generada automáticamente. Esta ruta es especialmente útil para aplicaciones solo de API que no sirven HTML, pero que sí quieren una pestaña de red limpia.
Paso 5: Verifica la configuración
Arranca tu servidor y abre la aplicación en un navegador. Comprueba la pestaña de red: la solicitud del favicon debería devolver un 200. Si ves un 404, verifica la ruta del archivo y que el punto de montaje coincida con la URL de tu link tag. También puedes usar una herramienta de comprobación de favicons para revisar el icono en distintos navegadores.
Errores comunes
- Ruta de montaje incorrecta: Si montas StaticFiles en
/static, la URL debe ser/static/favicon.ico, no/favicon.ico. - Archivo inexistente: FastAPI devolverá un 404 si el archivo no existe en el directorio. Comprueba que el nombre y la extensión sean correctos.
- Problemas de caché: Los navegadores almacenan los favicon en caché de forma agresiva. Después de actualizarlo, haz una recarga forzada o borra la caché del favicon. Consulta nuestra guía para limpiar la caché.
- SVG sin el MIME type correcto: Si sirves un favicon SVG, asegúrate de que el servidor envíe
image/svg+xml. StaticFiles normalmente se encarga de esto, pero algunas rutas personalizadas puede que no lo hagan. - Errores en la ruta de la plantilla: Si usas Jinja2, asegúrate de que el
hrefsea una ruta absoluta que empiece por/o utilizaurl_forpara generarla.
Conclusión
Servir un favicon en FastAPI consiste en colocar el archivo, montar un directorio estático y añadir la etiqueta link correcta. En las aplicaciones que solo ofrecen una API, una ruta sencilla para /favicon.ico mantiene limpios los logs. Una vez configurado, tu aplicación mostrará un icono adecuado en las pestañas, los marcadores y el historial del navegador: se acabaron los cuadrados en blanco.