キャッシュ

依存関係のキャッシュ

uvは、以前の実行で既にアクセスされた依存関係を再ダウンロード（および再ビルド）しないようにするために、積極的なキャッシュを使用します。

uvのキャッシュセマンティクスの詳細は、依存関係の性質に基づいて異なります：

レジストリ依存関係（PyPIからダウンロードされたものなど）については、uvはHTTPキャッシュヘッダーを尊重します。
直接URL依存関係については、uvはHTTPキャッシュヘッダーを尊重し、URL自体に基づいてキャッシュします。
Git依存関係については、uvは完全に解決されたGitコミットハッシュに基づいてキャッシュします。そのため、uv pip compileは解決された依存関係セットを書き込む際にGit依存関係を特定のコミットハッシュに固定します。
ローカル依存関係については、uvはソースアーカイブ（つまり、ローカルの.whlまたは.tar.gzファイル）の最終変更日時に基づいてキャッシュします。ディレクトリの場合、uvはpyproject.toml、setup.py、またはsetup.cfgファイルの最終変更日時に基づいてキャッシュします。

キャッシュの問題が発生している場合、uvにはいくつかのエスケープハッチがあります：

すべての依存関係のキャッシュデータを再検証するために、任意のコマンドに--refreshを渡します（例：uv sync --refreshまたはuv pip install --refresh ...）。
特定の依存関係のキャッシュデータを再検証するために、任意のコマンドに--refresh-dependencyを渡します（例：uv sync --refresh-package flaskまたはuv pip install --refresh-package flask ...）。
既存のインストール済みバージョンを無視するために、任意のインストールコマンドに--reinstallを渡します（例：uv sync --reinstallまたはuv pip install --reinstall ...）。

動的メタデータ

デフォルトでは、uvはローカルディレクトリ依存関係（例：編集可能なもの）を再ビルドおよび再インストールするのは、ディレクトリルートのpyproject.toml、setup.py、またはsetup.cfgファイルが変更された場合のみです。これはヒューリスティックであり、場合によっては望まれるよりも少ない再インストールを引き起こすことがあります。

特定のパッケージのキャッシュキーに他の情報を組み込むために、tool.uv.cache-keysの下にキャッシュキーエントリを追加できます。これにはファイルパスやGitコミットハッシュが含まれます。

たとえば、プロジェクトがsetuptools-scmを使用しており、コミットハッシュが変更されるたびに再ビルドする必要がある場合、プロジェクトのpyproject.tomlに次のように追加できます：

pyproject.toml

[tool.uv]
cache-keys = [{ git = { commit = true } }]

動的メタデータがGitタグのセットから情報を取得する場合、キャッシュキーをタグを含むように拡張できます：

pyproject.toml

[tool.uv]
cache-keys = [{ git = { commit = true, tags = true } }]

同様に、プロジェクトがrequirements.txtから依存関係を読み取る場合、プロジェクトのpyproject.tomlに次のように追加できます：

pyproject.toml

[tool.uv]
cache-keys = [{ file = "requirements.txt" }]

グロブがサポートされており、globクレートの構文に従います。たとえば、プロジェクトディレクトリまたはそのサブディレクトリ内の.tomlファイルが変更されるたびにキャッシュを無効にするには、次のようにします：

pyproject.toml

[tool.uv]
cache-keys = [{ file = "**/*.toml" }]

Note

グロブの使用は高価になる可能性があります。uvがファイルが変更されたかどうかを判断するためにファイルシステムをウォークする必要がある場合があります。これにより、大規模または深くネストされたディレクトリのトラバーサルが必要になる場合があります。

エスケープハッチとして、tool.uv.cache-keysでカバーされていないdynamicメタデータを使用するプロジェクトの場合、プロジェクトをtool.uv.reinstall-packageリストに追加することで、uvに常に再ビルドおよび再インストールさせることができます：

pyproject.toml

[tool.uv]
reinstall-package = ["my-package"]

これにより、パッケージのpyproject.toml、setup.py、またはsetup.cfgファイルが変更されたかどうかに関係なく、uvは毎回my-packageを再ビルドおよび再インストールします。

キャッシュの安全性

同じ仮想環境に対して複数のuvコマンドを同時に実行しても安全です。uvのキャッシュはスレッドセーフで追加専用に設計されており、複数の同時リーダーおよびライターに対して堅牢です。uvはインストール時にターゲット仮想環境にファイルベースのロックを適用し、プロセス間の同時変更を回避します。

uvコマンドが実行されている間にキャッシュを変更すること（例：uv cache clean）は安全ではなく、キャッシュを直接変更すること（例：ファイルやディレクトリを削除すること）は決して安全ではありません。

キャッシュのクリア

uvはキャッシュからエントリを削除するためのいくつかのメカニズムを提供します：

uv cache cleanはキャッシュディレクトリからすべてのキャッシュエントリを削除し、完全にクリアします。
uv cache clean ruffはruffパッケージのすべてのキャッシュエントリを削除し、特定のパッケージまたは有限のセットのパッケージのキャッシュを無効にするのに便利です。
uv cache pruneはすべての未使用のキャッシュエントリを削除します。たとえば、キャッシュディレクトリには、以前のuvバージョンで作成されたエントリが含まれている場合があり、それらはもはや必要なく、安全に削除できます。uv cache pruneは定期的に実行して、キャッシュディレクトリをクリーンに保つのが安全です。

継続的インテグレーションでのキャッシュ

継続的インテグレーション環境（GitHub ActionsやGitLab CIなど）では、パッケージインストールアーティファクトをキャッシュして、後続の実行を高速化することが一般的です。

デフォルトでは、uvはソースからビルドされたホイールと直接ダウンロードされた事前ビルドホイールの両方をキャッシュして、高性能なパッケージインストールを可能にします。

ただし、継続的インテグレーション環境では、事前ビルドホイールをキャッシュすることは望ましくない場合があります。uvでは、事前ビルドホイールをキャッシュから省略し（代わりに各実行時にレジストリから再ダウンロードする）、ソースからビルドされたホイールをキャッシュする方が高速であることがよくあります。特に拡張モジュールの場合、ホイールビルドプロセスは高価であるため、ソースからビルドされたホイールをキャッシュすることは価値があります。

このキャッシュ戦略をサポートするために、uvはuv cache prune --ciコマンドを提供しており、すべての事前ビルドホイールと解凍されたソースディストリビューションをキャッシュから削除しますが、ソースからビルドされたホイールは保持します。最大のキャッシュ効率を確保するために、継続的インテグレーションジョブの最後にuv cache prune --ciを実行することをお勧めします。例については、GitHub統合ガイドを参照してください。

キャッシュディレクトリ

uvは、次の順序でキャッシュディレクトリを決定します：

--no-cacheが要求された場合、一時的なキャッシュディレクトリ。
--cache-dir、UV_CACHE_DIR、またはtool.uv.cache-dirで指定された特定のキャッシュディレクトリ。
システムに適したキャッシュディレクトリ（例：Unixでは$XDG_CACHE_HOME/uvまたは$HOME/.cache/uv、Windowsでは%LOCALAPPDATA%\uv\cache）

Note

uvは常にキャッシュディレクトリを必要とします。--no-cacheが要求された場合でも、uvはその単一の呼び出し内でデータを共有するために一時的なキャッシュを使用します。

ほとんどの場合、--no-cacheの代わりに--refreshを使用する必要があります。これにより、キャッシュは後続の操作のために更新されますが、キャッシュから読み取られません。

キャッシュディレクトリがuvが操作しているPython環境と同じファイルシステム上にあることがパフォーマンスにとって重要です。そうでない場合、uvはキャッシュから環境にファイルをリンクできず、遅いコピー操作にフォールバックする必要があります。

キャッシュのバージョニング

uvのキャッシュは、バケットの数（例：ホイール用のバケット、ソースディストリビューション用のバケット、Gitリポジトリ用のバケットなど）で構成されています。各バケットはバージョン管理されており、リリースにキャッシュ形式の破壊的変更が含まれている場合、uvは互換性のないキャッシュバケットを読み書きしようとしません。

たとえば、uv 0.4.13にはコアメタデータバケットへの破壊的変更が含まれていました。そのため、バケットバージョンはv12からv13に増加しました。キャッシュバージョン内では、変更は前方互換性および後方互換性が保証されています。

キャッシュ形式の変更はキャッシュバージョンの変更を伴うため、複数のuvバージョンが同じキャッシュディレクトリを安全に読み書きできます。ただし、キャッシュバージョンが特定のuvリリース間で変更された場合、それらのリリースは同じ基盤となるキャッシュエントリを共有できない場合があります。

たとえば、uv 0.4.12とuv 0.4.13の単一の共有キャッシュを使用することは安全ですが、キャッシュバージョンの変更により、コアメタデータバケットに重複するエントリが含まれる場合があります。