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:

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.html

Si 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

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.