Skip to content

Cachingキャッシング

Dependency caching依存関係のキャッシング

uv uses aggressive caching to avoid re-downloading (and re-building) dependencies that have already been accessed in prior runs.uvは、以前の実行で既にアクセスされた依存関係を再ダウンロード（および再ビルド）しないように、積極的なキャッシングを使用します。

The specifics of uv's caching semantics vary based on the nature of the dependency:uvのキャッシングセマンティクスの具体的な内容は、依存関係の性質に基づいて異なります：

  • For registry dependencies (like those downloaded from PyPI), uv respects HTTP caching headers.レジストリ依存関係（PyPIからダウンロードされたものなど）については、uvはHTTPキャッシングヘッダーを尊重します。
  • For direct URL dependencies, uv respects HTTP caching headers, and also caches based on the URL itself.直接URL依存関係については、uvはHTTPキャッシングヘッダーを尊重し、URL自体に基づいてもキャッシュします。
  • For Git dependencies, uv caches based on the fully-resolved Git commit hash. As such, uv pip compile will pin Git dependencies to a specific commit hash when writing the resolved dependency set.Git依存関係の場合、uvは完全に解決されたGitコミットハッシュに基づいてキャッシュします。そのため、uv pip compileは解決された依存関係セットを書き込む際に、Git依存関係を特定のコミットハッシュに固定します。
  • For local dependencies, uv caches based on the last-modified time of the source archive (i.e., the local .whl or .tar.gz file). For directories, uv caches based on the last-modified time of the pyproject.toml, setup.py, or setup.cfg file.ローカル依存関係の場合、uvはソースアーカイブの最終更新時刻（つまり、ローカルの.whlまたは.tar.gzファイル）に基づいてキャッシュします。ディレクトリの場合、uvはpyproject.toml、setup.py、またはsetup.cfgファイルの最終更新時刻に基づいてキャッシュします。

If you're running into caching issues, uv includes a few escape hatches:キャッシュの問題が発生している場合、uvにはいくつかの逃げ道があります：

  • To clear the cache entirely, run uv cache clean. To clear the cache for a specific package, run uv cache clean <package-name>. For example, uv cache clean ruff will clear the cache for the ruff package.キャッシュを完全にクリアするには、uv cache cleanを実行します。特定のパッケージのキャッシュをクリアするには、uv cache clean <package-name>を実行します。たとえば、uv cache clean ruffはruffパッケージのキャッシュをクリアします。
  • To force uv to revalidate cached data for all dependencies, pass --refresh to any command (e.g., uv sync --refresh or uv pip install --refresh ...).すべての依存関係のキャッシュデータを再検証するには、任意のコマンドに--refreshを渡します（例：uv sync --refreshまたはuv pip install --refresh ...）。
  • To force uv to revalidate cached data for a specific dependency pass --refresh-package to any command (e.g., uv sync --refresh-package ruff or uv pip install --refresh-package ruff ...).特定の依存関係のキャッシュデータを再検証するには、任意のコマンドに--refresh-packageを渡します（例：uv sync --refresh-package ruffまたはuv pip install --refresh-package ruff ...）。
  • To force uv to ignore existing installed versions, pass --reinstall to any installation command (e.g., uv sync --reinstall or uv pip install --reinstall ...). (Consider running uv cache clean <package-name> first, to ensure that the cache is cleared prior to reinstallation.)既存のインストール済みバージョンを無視するようuvに強制するには、任意のインストールコマンドに--reinstallを渡します（例：uv sync --reinstallまたはuv pip install --reinstall ...）。（再インストールの前にキャッシュがクリアされることを確認するために、最初にuv cache clean <package-name>を実行することを検討してください。）

As a special case, uv will always rebuild and reinstall any local directory dependencies passed explicitly on the command-line (e.g., uv pip install .).特別なケースとして、uvはコマンドラインで明示的に渡されたローカルディレクトリ依存関係を常に再構築および再インストールします（例：uv pip install .）。

Dynamic metadata動的メタデータ

By default, uv will only rebuild and reinstall local directory dependencies (e.g., editables) if the pyproject.toml, setup.py, or setup.cfg file in the directory root has changed, or if a src directory is added or removed. This is a heuristic and, in some cases, may lead to fewer re-installs than desired.デフォルトでは、uvはローカルディレクトリ依存関係（例：editable）を再構築および再インストールするのは、ディレクトリのルートにあるpyproject.toml、setup.py、またはsetup.cfgファイルが変更された場合、またはsrcディレクトリが追加または削除された場合のみです。これはヒューリスティックであり、場合によっては望ましいよりも再インストールが少なくなる可能性があります。

To incorporate additional information into the cache key for a given package, you can add cache key entries under tool.uv.cache-keys, which covers both file paths and Git commit hashes. Setting tool.uv.cache-keys will replace defaults, so any necessary files (like pyproject.toml) should still be included in the user-defined cache keys.特定のパッケージのキャッシュキーに追加情報を組み込むには、tool.uv.cache-keysの下にキャッシュキーエントリを追加できます。これにはファイルパスとGitコミットハッシュの両方が含まれます。tool.uv.cache-keysを設定すると、デフォルトが置き換えられるため、必要なファイル（pyproject.tomlなど）はユーザー定義のキャッシュキーに含める必要があります。

For example, if a project specifies dependencies in pyproject.toml but uses setuptools-scm to manage its version, and should thus be rebuilt whenever the commit hash or dependencies change, you can add the following to the project's pyproject.toml:例えば、プロジェクトがpyproject.tomlで依存関係を指定しているが、setuptools-scmを使用してバージョンを管理している場合、コミットハッシュや依存関係が変更されるたびに再構築する必要があります。その場合、プロジェクトのpyproject.tomlに以下を追加できます：

pyproject.toml
[tool.uv]
cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true } }]

If your dynamic metadata incorporates information from the set of Git tags, you can expand the cache key to include the tags:動的メタデータがGitタグのセットから情報を取り込む場合、キャッシュキーをタグを含むように拡張できます：

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

Similarly, if a project reads from a requirements.txt to populate its dependencies, you can add the following to the project's pyproject.toml:同様に、プロジェクトが依存関係を埋め込むためにrequirements.txtを読み込む場合、プロジェクトのpyproject.tomlに以下を追加できます：

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

Globs are supported for file keys, following the syntax of the glob crate. For example, to invalidate the cache whenever a .toml file in the project directory or any of its subdirectories is modified, use the following:グロブはfileキーに対してサポートされており、globクレートの構文に従います。例えば、プロジェクトディレクトリまたはそのサブディレクトリ内の.tomlファイルが変更されるたびにキャッシュを無効にするには、以下を使用します：

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

Note注意

The use of globs can be expensive, as uv may need to walk the filesystem to determine whether any files have changed. This may, in turn, requiring traversal of large or deeply nested directories.グロブの使用はコストがかかる場合があり、uvがファイルシステムを歩いてファイルが変更されたかどうかを判断する必要があるかもしれません。これにより、大きなディレクトリや深くネストされたディレクトリのトラバースが必要になることがあります。

Similarly, if a project relies on an environment variable, you can add the following to the project's pyproject.toml to invalidate the cache whenever the environment variable changes:同様に、プロジェクトが環境変数に依存している場合、環境変数が変更されるたびにキャッシュを無効にするために、プロジェクトのpyproject.tomlに以下を追加できます：

pyproject.toml
[tool.uv]
cache-keys = [{ file = "pyproject.toml" }, { env = "MY_ENV_VAR" }]

Finally, to invalidate a project whenever a specific directory (like src) is created or removed, add the following to the project's pyproject.toml:最後に、特定のディレクトリ（srcなど）が作成または削除されるたびにプロジェクトを無効にするには、プロジェクトのpyproject.tomlに以下を追加します：

pyproject.toml
[tool.uv]
cache-keys = [{ file = "pyproject.toml" }, { dir = "src" }]

Note that the dir key will only track changes to the directory itself, and not arbitrary changes within the directory.dirキーはディレクトリ自体の変更のみを追跡し、ディレクトリ内の任意の変更は追跡しないことに注意してください。

As an escape hatch, if a project uses dynamic metadata that isn't covered by tool.uv.cache-keys, you can instruct uv to always rebuild and reinstall it by adding the project to the tool.uv.reinstall-package list:エスケープハッチとして、プロジェクトがtool.uv.cache-keysでカバーされていないdynamicメタデータを使用している場合、プロジェクトをtool.uv.reinstall-packageリストに追加することで、uvに常に再構築および再インストールするよう指示できます：

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

This will force uv to rebuild and reinstall my-package on every run, regardless of whether the package's pyproject.toml, setup.py, or setup.cfg file has changed.これにより、パッケージの pyproject.toml、setup.py、または setup.cfg ファイルが変更されているかどうかに関係なく、毎回 my-package を再構築して再インストールするように uv が強制されます。

Cache safetyキャッシュの安全性

It's safe to run multiple uv commands concurrently, even against the same virtual environment. uv's cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent readers and writers. uv applies a file-based lock to the target virtual environment when installing, to avoid concurrent modifications across processes.同じ仮想環境に対して複数の uv コマンドを同時に実行することは安全です。uv のキャッシュはスレッドセーフで追加専用に設計されており、複数の同時リーダーおよびライターに対して堅牢です。uv はインストール時にターゲットの仮想環境にファイルベースのロックを適用し、プロセス間の同時変更を避けます。

Note that it's not safe to modify the uv cache (e.g., uv cache clean) while other uv commands are running, and never safe to modify the cache directly (e.g., by removing a file or directory).他の uv コマンドが実行中の間に uv キャッシュを変更すること（例：uv cache clean）は安全ではないことに注意してください。また、キャッシュを直接変更すること（例：ファイルやディレクトリを削除すること）は決して安全ではありません。

Clearing the cacheキャッシュのクリア

uv provides a few different mechanisms for removing entries from the cache:uv はキャッシュからエントリを削除するためのいくつかの異なるメカニズムを提供します：

  • uv cache clean removes all cache entries from the cache directory, clearing it out entirely.uv cache clean はキャッシュディレクトリからすべてのキャッシュエントリを削除し、完全にクリアします。
  • 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 clean ruff は ruff パッケージのすべてのキャッシュエントリを削除し、単一または有限のパッケージセットのキャッシュを無効にするのに便利です。
  • 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.uv cache prune はすべての未使用キャッシュエントリを削除します。たとえば、キャッシュディレクトリには、もはや必要ない以前の uv バージョンで作成されたエントリが含まれている場合があり、安全に削除できます。uv cache prune は定期的に実行してキャッシュディレクトリをクリーンに保つのが安全です。

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.しかし、継続的インテグレーション環境では、プリビルドホイールを保持することが望ましくない場合があります。uvを使用すると、キャッシュからプリビルドホイールを省略し（代わりに各実行時にレジストリから再ダウンロードする方がしばしば速いことがわかります）。一方で、ソースからビルドされたホイールをキャッシュすることは価値がある傾向があります。なぜなら、ホイールビルドプロセスは高コストである可能性があり、特に拡張モジュールの場合はそうです。

To support this caching strategy, uv provides a uv cache prune --ci command, which removes all pre-built wheels and unzipped source distributions 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統合ガイドを参照してください。

Cache directoryキャッシュディレクトリ

uv determines the cache directory according to, in order:uvは、次の順序でキャッシュディレクトリを決定します：

  1. A temporary cache directory, if --no-cache was requested.--no-cacheが要求された場合、一時的なキャッシュディレクトリ。
  2. The specific cache directory specified via --cache-dir, UV_CACHE_DIR, or tool.uv.cache-dir.--cache-dir、UV_CACHE_DIR、またはtool.uv.cache-dirを介して指定された特定のキャッシュディレクトリ。
  3. A system-appropriate cache directory, e.g., $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Unix and %LOCALAPPDATA%\uv\cache on Windowsシステムに適したキャッシュディレクトリ、例えば、Unixでは$XDG_CACHE_HOME/uvまたは$HOME/.cache/uv、Windowsでは%LOCALAPPDATA%\uv\cache

Note注意

uv always requires a cache directory. When --no-cache is requested, uv will still use a temporary cache for sharing data within that single invocation.uvは常にキャッシュディレクトリを必要とします。--no-cacheが要求された場合でも、uvはその単一の呼び出し内でデータを共有するために一時的なキャッシュを使用します。

In most cases, --refresh should be used instead of --no-cache — as it will update the cache for subsequent operations but not read from the cache.ほとんどの場合、--refreshを使用するべきです。--no-cacheの代わりに使用することで、次の操作のためにキャッシュを更新しますが、キャッシュからは読み込みません。

It is important for performance for the cache directory to be located on the same file system as the Python environment uv is operating on. Otherwise, uv will not be able to link files from the cache into the environment and will instead need to fallback to slow copy operations.パフォーマンスのために、キャッシュディレクトリはPython環境uvが動作しているのと同じファイルシステム上にあることが重要です。そうでない場合、uvはキャッシュからファイルを環境にリンクできず、遅いコピー操作にフォールバックする必要があります。

Cache versioningキャッシュのバージョン管理

The uv cache is composed of a number of buckets (e.g., a bucket for wheels, a bucket for source distributions, a bucket for Git repositories, and so on). Each bucket is versioned, such that if a release contains a breaking change to the cache format, uv will not attempt to read from or write to an incompatible cache bucket.uvキャッシュは、いくつかのバケット（例：ホイール用のバケット、ソース配布用のバケット、Gitリポジトリ用のバケットなど）で構成されています。各バケットはバージョン管理されており、リリースにキャッシュフォーマットへの破壊的変更が含まれている場合、uvは互換性のないキャッシュバケットから読み取ったり書き込んだりしようとはしません。

For example, uv 0.4.13 included a breaking change to the core metadata bucket. As such, the bucket version was increased from v12 to v13. Within a cache version, changes are guaranteed to be both forwards- and backwards-compatible.例えば、uv 0.4.13はコアメタデータバケットに破壊的変更を含んでいました。そのため、バケットのバージョンはv12からv13に増加しました。キャッシュバージョン内では、変更は前方互換性と後方互換性の両方が保証されています。

Since changes in the cache format are accompanied by changes in the cache version, multiple versions of uv can safely read and write to the same cache directory. However, if the cache version changed between a given pair of uv releases, then those releases may not be able to share the same underlying cache entries.キャッシュフォーマットの変更はキャッシュバージョンの変更を伴うため、複数のuvバージョンが同じキャッシュディレクトリを安全に読み書きできます。ただし、特定のuvリリースのペア間でキャッシュバージョンが変更された場合、それらのリリースは同じ基盤キャッシュエントリを共有できない可能性があります。

For example, it's safe to use a single shared cache for uv 0.4.12 and uv 0.4.13, though the cache itself may contain duplicate entries in the core metadata bucket due to the change in cache version.例えば、uv 0.4.12とuv 0.4.13のために単一の共有キャッシュを使用することは安全ですが、キャッシュ自体はキャッシュバージョンの変更によりコアメタデータバケットに重複エントリを含む可能性があります。