本記事は執筆にあたり、AIによる内容の構成案およびレビューの支援を受けています。

背景

Uvicornでの開発時、--reloadオプションは非常に便利ですが、特定のフォルダ（一時ファイル保存先など）の変更で再起動してほしくない場合があります。

その際、--reload-excludeを指定したにもかかわらず、「なぜか無視されて再起動が走ってしまう」 という現象に遭遇しました。

AIに聞いても--reload-excludeに除外したいフォルダを指定してください、という旨の回答しかなく、悩んだ挙句、原因がわかって拍子抜けしたので備忘録として残します。

結論：`watchfiles` のインストールが必要

Uvicorn標準のリロード機能ではなく、より高度なファイル監視を行うには watchfiles というライブラリが必要です。

--reload-include や --reload-exclude は、この watchfiles がインストールされている場合にのみ動作するオプションでした。

# これをインストールするだけで解決します
pip install watchfiles

試したこと（経緯）

解決に至るまで、以下の挙動を確認しました。

--reload-exclude 'temp/*' を指定 → NG（無視される）
--reload-include 'src/*' を指定 → NG（無視される）
--reload-dir src を指定 → OK（監視対象が限定されるため、実質解決する）

当時は暫定的に --reload-dir で凌いでいましたが、根本的な原因はオプションを処理するためのライブラリ不足でした。

公式ドキュメントの記載

Uvicorn公式ドキュメントを確認すると、以下のように記載されています。

--reload-include - ... This option has no effect unless watchfiles is installed.
--reload-exclude - ... This option has no effect unless watchfiles is installed.

日本語訳：watchfiles がインストールされていない限り、このオプションは効果を持ちません。

おわりに

「AIが教えてくれなかった」という点についても、おそらくAIは「オプションが存在すること」は知っていても、「特定のライブラリに依存していること」を見落としがちです。

同じように「オプションを指定しているのに動かない！」と悩んでいる方の助けになれば幸いです。

参考文献

Uvicorn公式ドキュメント