FastAPI アプリを動かしていて、API ドキュメントはきれいに表示されているのに、ブラウザーのタブには空の四角やデフォルトの地球アイコンが表示されたままという状態かもしれません。これはよくある問題です。FastAPI は favicon を自動的に配信せず、Flask や Django のように favicon 用の built-in convention もありません。ファイルの置き場所と公開方法を知っていれば、対処は簡単です。

このガイドでは、StaticFiles、専用の route、または template tag を使って fastapi favicon を配信する具体的な手順を説明します。ブラウザーが icon を確実に取得できるようにする HTML markup も扱います。また、404 や古い icon を招く落とし穴も取り上げます。

前提条件

始める前に、次のものを用意してください。

手順1: favicon ファイルを static ディレクトリに配置する

プロジェクトのルート(または好きな場所)に static という名前のフォルダを作成します。その中に favicon ファイルを配置してください。互換性を最大限高めるには、favicon.ico という名前にし、PNG や SVG のバージョンもあれば併せて配置してください。

myproject/
├── main.py
├── static/
│   └── favicon.ico
└── templates/
    └── index.html

PNG しかない場合も、正しく HTML で参照すれば動作します。link tag がない場合でもブラウザーは ICO format を引き続きリクエストするため、/favicon.ico を用意しておけば、console に 404 が出るのを避けられます。

手順2: FastAPI app に StaticFiles を mount する

FastAPI は Starlette の StaticFiles を使って static assets を配信します。main.py に次を追加します:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

app.mount('/static', StaticFiles(directory='static'), name='static')

これにより、static/ 内のすべてのファイルを /static/filename で配信できます。したがって、favicon は /static/favicon.ico に配置されます。

手順3: HTML に link tag を追加する

HTMLテンプレート(Jinja2Templatesを使用)を配信する場合は、ベーステンプレートの<head>内にfaviconのlinkを追加してください。rel属性は、HTML specificationによるとiconでなければなりません。

<link rel='icon' type='image/x-icon' href='/static/favicon.ico'>

SVGやPNGも用意している場合は、適切なtype属性を付けて指定します。ブラウザーはサポートされている形式のうち最適なものを選びます。link tagの順序については、さらに詳しくfavicon link tag guideを参照してください。

Step 4: /favicon.icoを直接配信する(任意ですが推奨)

link tagがあっても、ブラウザーや一部のツールは依然としてルートで/favicon.icoをリクエストします。404を避けるには、ファイルを返す専用routeを追加できます。

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')

include_in_schema=Falseを指定すると、自動生成されるドキュメントから除外されます。このルートは、HTMLを配信しないAPI-only appでも、Networkタブをきれいに保ちたい場合に特に便利です。

Step 5: セットアップを確認する

サーバーを起動して、ブラウザーでアプリを開きます。Networkタブを確認し、faviconのリクエストが200を返すことを確認してください。404が表示される場合は、file pathと、link tagのURLに一致するmount pointを確認してください。また、favicon checker toolを使って、ブラウザー間でiconを監査することもできます。

よくある落とし穴

まとめ

FastAPIでfaviconを提供する上で必要なのは、ファイルを配置し、static directoryをマウントして、適切なlink tagを追加することです。API-only appでは、/favicon.ico用のsimple routeを用意すれば、logをきれいに保てます。設定が完了すると、ブラウザのタブ、ブックマーク、履歴に適切なアイコンが表示され、空欄の正方形はもう 나타나ません。