Skip to content

Caching#

Dependency caching#

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コマンドを同時に実行することは安全です。uvのキャッシュはスレッドセーフで追加専用に設計されているため、複数の同時読み取り/書き込みに対して堅牢です。uvは、インストール時にターゲット仮想環境にファイルベースのロックを適用して、プロセス間での同時変更を回避します。

他のuvコマンドの実行中にuvキャッシュを変更すること(例えばuv cache clean)は_安全ではありません_。また、キャッシュを直接変更すること(例えばファイルやディレクトリを削除すること)は_決して安全ではありません_。

キャッシュの問題が発生した場合、uvにはいくつかのエスケープハッチが含まれます。:

  • すべての依存関係に対してキャッシュされたデータを強制的に再検証するには、uv pip install --refresh ...を実行します。
  • uvに特定の依存関係に対してキャッシュされたデータの再検証を強制するには、例えばuv pip install --refresh-package flask ...を実行します。
  • uvがインストール済みの既存のバージョンを無視するようにするには、uv pip install --reinstall ...を実行します。

Clearing the cache#

uvには、キャッシュからエントリを削除するためのメカニズムがいくつか用意されています。

  • uv cache clean removes all cache entries from the cache directory, clearing it out entirely.
  • uv cache clean ruff removes all cache entries for the ruff package, useful for invalidating the cache for a single or finite set of packages.
  • uv cache prune removes all unused cache entries. For example, the cache directory may contain entries created in previous uv versions that are no longer necessary and can be safely removed. uv cache prune is safe to run periodically, to keep the cache directory clean.

Caching in continuous integration#

It's common to cache package installation artifacts in continuous integration environments (like GitHub Actions or GitLab CI) to speed up subsequent runs.

その後の実行を高速化するために、継続的インテグレーション環境(GitHub ActionsやGitLab CIなど)でパッケージインストールアーティファクトをキャッシュするのが一般的である。

By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, to enable high-performance package installation.

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

However, in continuous integration environments, persisting pre-built wheels may be undesirable. With uv, it turns out that it's often faster to omit pre-built wheels from the cache (and instead re-download them from the registry on each run). On the other hand, caching wheels that are built from source tends to be worthwhile, since the wheel building process can be expensive, especially for extension modules.

ただし、継続的インテグレーション環境では、事前に構築されたWheelを保持することは望ましくない場合があります。uvでは、キャッシュから事前に構築されたWheelを_省略_する方が(代わりに、実行ごとにレジストリから再ダウンロードする方が)高速であることがよくあります。一方、ソースから構築されたWheelをキャッシュすることは、特に拡張モジュールの場合、Wheel構築プロセスが高価になる可能性があるため、価値がある傾向があります。

To support this caching strategy, uv provides a uv cache prune --ci command, which removes all pre-built wheels from the cache but retains any wheels that were built from source. We recommend running uv cache prune --ci at the end of your continuous integration job to ensure maximum cache efficiency. For an example, see the GitHub integration guide.

このキャッシング戦略をサポートするために、uvにはuv cache prune --ciコマンドが用意されています。このコマンドは、事前に構築されたすべてのホイールをキャッシュから削除しますが、ソースから構築されたホイールは保持します。キャッシュ効率を最大限に高めるために、継続的な統合ジョブの最後にuv cache prune --ciを実行することをお勧めします。例については、GitHub integration guideを参照してください。